@openclaw/matrix 2026.9.5 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/replace-file-descriptor.js

@@ -0,0 +1,168 @@
+import { syncFileBestEffort, syncFileBestEffortSync } from "./file-sync.js";
+import syncFs, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+import { ownDirectoryMode } from "./directory-mode-node.js";
+export async function syncDirectoryBestEffort(fsModule, dirPath) {
+    let handle;
+    try {
+        handle = await fsModule.open(dirPath, "r");
+        await handle.sync();
+    }
+    catch {
+        // Best-effort on platforms/filesystems that do not support directory fsync.
+    }
+    finally {
+        try {
+            await handle?.close();
+        }
+        catch {
+            // Best-effort close also covers synchronous adapter throws.
+        }
+    }
+}
+export function syncDirectoryBestEffortSync(fsModule, dirPath) {
+    let fd;
+    try {
+        fd = fsModule.openSync(dirPath, "r");
+        fsModule.fsyncSync(fd);
+    }
+    catch {
+        // Best-effort on platforms/filesystems that do not support directory fsync.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fsModule.closeSync(fd);
+            }
+            catch {
+                // Best-effort close after directory fsync.
+            }
+        }
+    }
+}
+function directoryOpenFlags() {
+    return (syncFs.constants.O_RDONLY |
+        syncFs.constants.O_DIRECTORY |
+        syncFs.constants.O_NOFOLLOW |
+        syncFs.constants.O_NONBLOCK);
+}
+function assertDirectory(identity, dirPath) {
+    if (identity.isSymbolicLink() || !identity.isDirectory()) {
+        throw new FsSafeError("not-file", `Atomic replace parent must be a real directory: ${dirPath}`);
+    }
+    return identity;
+}
+export async function pinDirectoryForMode(params) {
+    // Node does not enforce POSIX directory modes on Windows, and its directory
+    // descriptors are not consistently openable. mkdir(mode) remains the only
+    // bounded behavior there; never fall back to a pathname chmod.
+    if (process.platform === "win32") {
+        return;
+    }
+    const expected = params.fsModule === fs
+        ? inspectFileIdentitySync(() => assertDirectory(syncFs.lstatSync(params.dirPath, { bigint: true }), params.dirPath))
+        : await inspectFileIdentity(async () => assertDirectory(await params.fsModule.lstat(params.dirPath, { bigint: true }), params.dirPath));
+    const handle = await params.fsModule.open(params.dirPath, directoryOpenFlags());
+    try {
+        const owner = ownDirectoryMode({
+            async inspect() {
+                const opened = params.fsModule === fs
+                    ? inspectFileIdentitySync(() => assertDirectory(syncFs.fstatSync(handle.fd, { bigint: true }), params.dirPath), expected)
+                    : await inspectFileIdentity(async () => assertDirectory(await handle.stat({ bigint: true }), params.dirPath), expected);
+                return Number(opened.mode & 4095n);
+            },
+            chmod: (mode) => {
+                params.mutation?.assert();
+                return handle.chmod(mode);
+            },
+            close: () => handle.close(),
+            ignoreChmodError: params.ignoreChmodError,
+        });
+        await owner.verify();
+        return owner;
+    }
+    catch (error) {
+        await handle.close();
+        throw error;
+    }
+}
+export async function applyDirectoryMode(params) {
+    const owner = await pinDirectoryForMode(params);
+    try {
+        await owner?.apply(params.mode);
+    }
+    finally {
+        await owner?.close();
+    }
+}
+export function applyDirectoryModeSync(params) {
+    if (process.platform === "win32") {
+        return;
+    }
+    const expected = inspectFileIdentitySync(() => assertDirectory(params.fsModule.lstatSync(params.dirPath, { bigint: true }), params.dirPath));
+    const fd = params.fsModule.openSync(params.dirPath, directoryOpenFlags());
+    try {
+        inspectFileIdentitySync(() => assertDirectory(params.fsModule.fstatSync(fd, { bigint: true }), params.dirPath), expected);
+        // chmod ignores file-type bits; mask so raw stat modes are tolerated.
+        params.mutation?.assert();
+        params.fchmodSync?.(fd, params.mode & 0o7777);
+    }
+    finally {
+        params.fsModule.closeSync(fd);
+    }
+}
+export async function writeTempFile(params) {
+    params.mutation?.assert();
+    const handle = await params.fsModule.open(params.tempPath, "wx", params.mode);
+    try {
+        // Custom adapters retain their async-only metadata contract.
+        const inspect = () => params.fsModule === fs
+            ? syncFs.fstatSync(handle.fd, { bigint: true }) : handle.stat({ bigint: true });
+        const identity = await inspectFileIdentity(inspect);
+        params.onIdentity?.(identity);
+        params.mutation?.assert();
+        await params.fsModule.writeFile(handle, params.content);
+        await handle.chmod(params.mode);
+        if (params.sync) {
+            await syncFileBestEffort(handle);
+        }
+        await inspectFileIdentity(inspect, identity);
+        return { handle, identity };
+    }
+    catch (error) {
+        try {
+            await handle.close();
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], "Atomic temp write and close failed");
+        }
+        throw error;
+    }
+}
+export function writeTempFileSync(params) {
+    params.mutation?.assert();
+    const fd = params.fsModule.openSync(params.tempPath, "wx", params.mode);
+    try {
+        const identity = inspectFileIdentitySync(() => params.fsModule.fstatSync(fd, { bigint: true }));
+        params.onIdentity?.(identity);
+        params.mutation?.assert();
+        params.fsModule.writeFileSync(fd, params.content);
+        params.fchmodSync?.(fd, params.mode);
+        if (params.sync) {
+            syncFileBestEffortSync(fd, params.fsModule);
+        }
+        inspectFileIdentitySync(() => params.fsModule.fstatSync(fd, { bigint: true }), identity);
+        return { fd, identity };
+    }
+    catch (error) {
+        try {
+            params.fsModule.closeSync(fd);
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], "Atomic temp write and close failed");
+        }
+        throw error;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/replace-file-destination.d.ts

@@ -0,0 +1,21 @@
+import fsSync from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+import type { AtomicMutation } from "./replace-file-mutation.js";
+/** Borrow the writer's descriptor; never adopt an identity from a later pathname open. */
+export declare function captureAtomicDestination(fsModule: Pick<typeof fs, "lstat">, handle: FileHandle, pathname: string, mutation: AtomicMutation, rejectHardlinks: boolean): Promise<{
+    verify: () => Promise<void>;
+    writing: () => void;
+    beforeWrite: () => Promise<void>;
+    beforeRestore: () => Promise<void>;
+    verifyRestore: () => Promise<void>;
+    assertBeforeMutation: () => void;
+    published: () => void;
+}>;
+export declare function captureAtomicDestinationSync(fsModule: Pick<typeof fsSync, "lstatSync" | "fstatSync">, fd: number, pathname: string, mutation: AtomicMutation, rejectHardlinks: boolean): {
+    verify: () => void;
+    writing: () => void;
+    beforeWrite: () => void;
+    beforeRestore: () => void;
+    verifyRestore: () => void;
+    published: () => void;
+};

package/node_modules/@openclaw/fs-safe/dist/replace-file-destination.js

@@ -0,0 +1,123 @@
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { hasErrorCode } from "./file-cleanup.js";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+function regular(stat, pathname, rejectHardlinks) {
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new FsSafeError("path-mismatch", `Atomic replace destination changed: ${pathname}`);
+    }
+    if (rejectHardlinks && stat.nlink !== 1n) {
+        throw new FsSafeError("hardlink", `Hardlinked atomic replace destination not allowed: ${pathname}`);
+    }
+    return stat;
+}
+/** Borrow the writer's descriptor; never adopt an identity from a later pathname open. */
+export async function captureAtomicDestination(fsModule, handle, pathname, mutation, rejectHardlinks) {
+    const inspect = () => fsModule === fs
+        ? fsSync.fstatSync(handle.fd, { bigint: true }) : handle.stat({ bigint: true });
+    const identity = await inspectFileIdentity(inspect);
+    regular(identity, pathname, rejectHardlinks);
+    let writing = false;
+    let restoreDescriptorOnly = false;
+    const verifyDescriptor = async () => {
+        await inspectFileIdentity(async () => regular(await inspect(), pathname, rejectHardlinks), identity);
+    };
+    const verify = async () => {
+        let metadataFailure = false;
+        const observe = async (read) => {
+            try {
+                return await read();
+            }
+            catch (error) {
+                metadataFailure = hasErrorCode(error, "EIO");
+                throw error;
+            }
+        };
+        try {
+            await inspectFileIdentity(async () => regular(await observe(inspect), pathname, rejectHardlinks), identity);
+            await inspectFileIdentity(async () => regular(await observe(() => fsModule.lstat(pathname, { bigint: true })), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            if (writing && metadataFailure) {
+                // A metadata observation failed, but the already-owned descriptor can
+                // still restore its bytes after fresh exact descriptor verification.
+                restoreDescriptorOnly = true;
+                throw error;
+            }
+            mutation.refuse(error);
+        }
+    };
+    const verifyRestore = async () => {
+        if (!restoreDescriptorOnly)
+            return await verify();
+        try {
+            await verifyDescriptor();
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => { writing = true; mutation.destination("writing", pathname, identity); },
+        beforeWrite: async () => {
+            mutation.assert();
+            await verify();
+        },
+        beforeRestore: async () => { mutation.assert(); await verifyRestore(); },
+        verifyRestore,
+        assertBeforeMutation: () => mutation.assert(),
+        published: () => mutation.destination("published", pathname, identity),
+    };
+}
+export function captureAtomicDestinationSync(fsModule, fd, pathname, mutation, rejectHardlinks) {
+    const identity = inspectFileIdentitySync(() => fsModule.fstatSync(fd, { bigint: true }));
+    regular(identity, pathname, rejectHardlinks);
+    let writing = false;
+    let restoreDescriptorOnly = false;
+    const verify = () => {
+        let metadataFailure = false;
+        const observe = (read) => {
+            try {
+                return read();
+            }
+            catch (error) {
+                metadataFailure = hasErrorCode(error, "EIO");
+                throw error;
+            }
+        };
+        try {
+            inspectFileIdentitySync(() => regular(observe(() => fsModule.fstatSync(fd, { bigint: true })), pathname, rejectHardlinks), identity);
+            inspectFileIdentitySync(() => regular(observe(() => fsModule.lstatSync(pathname, { bigint: true })), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            if (writing && metadataFailure) {
+                restoreDescriptorOnly = true;
+                throw error;
+            }
+            mutation.refuse(error);
+        }
+    };
+    const verifyRestore = () => {
+        if (!restoreDescriptorOnly)
+            return verify();
+        try {
+            inspectFileIdentitySync(() => regular(fsModule.fstatSync(fd, { bigint: true }), pathname, rejectHardlinks), identity);
+        }
+        catch (error) {
+            mutation.refuse(error);
+        }
+    };
+    return {
+        verify,
+        writing: () => { writing = true; mutation.destination("writing", pathname, identity); },
+        beforeWrite: () => {
+            mutation.assert();
+            verify();
+        },
+        beforeRestore: () => { mutation.assert(); verifyRestore(); },
+        verifyRestore,
+        published: () => mutation.destination("published", pathname, identity),
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/replace-file-mode.d.ts

@@ -0,0 +1,2 @@
+import type { Stats } from "node:fs";
+export declare function inheritedRegularFileMode(stat: Stats): number;

package/node_modules/@openclaw/fs-safe/dist/replace-file-mode.js

@@ -0,0 +1,10 @@
+import { FsSafeError } from "./errors.js";
+export function inheritedRegularFileMode(stat) {
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("symlink", "atomic replace destination must not be a symbolic link");
+    }
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "atomic replace destination must be a regular file");
+    }
+    return stat.mode & 0o777;
+}

package/node_modules/@openclaw/fs-safe/dist/replace-file-mutation.d.ts

@@ -0,0 +1,26 @@
+import type { BigIntStats } from "node:fs";
+export type ReplaceFileAtomicDestinationState = Readonly<{
+    state: "removed";
+    path: string;
+}> | Readonly<{
+    state: "writing" | "published";
+    path: string;
+    dev: bigint;
+    ino: bigint;
+}>;
+export type AtomicMutationOptions = {
+    /** Recheck live authority before new effects; retained descriptor completion may settle. */
+    assertBeforeMutation?: () => void;
+    /** Retain observed destination facts even when later completion fails. */
+    onDestinationState?: (state: ReplaceFileAtomicDestinationState) => void;
+};
+export declare class AtomicMutation {
+    #private;
+    readonly active: boolean;
+    constructor(options: AtomicMutationOptions);
+    rethrowRefusal(): void;
+    refuse(error: unknown): never;
+    assert(): void;
+    destination(state: "writing" | "published", path: string, identity: BigIntStats): void;
+    removed(path: string): void;
+}

package/node_modules/@openclaw/fs-safe/dist/replace-file-mutation.js

@@ -0,0 +1,47 @@
+import { assertSynchronousCallbackResult } from "./mutation-authority.js";
+export class AtomicMutation {
+    active;
+    #assertion;
+    #observer;
+    #refusal;
+    #writingReported = false;
+    constructor(options) {
+        this.#assertion = options.assertBeforeMutation;
+        this.#observer = options.onDestinationState;
+        this.active = Boolean(this.#assertion || this.#observer);
+    }
+    rethrowRefusal() {
+        if (this.#refusal)
+            throw this.#refusal.error;
+    }
+    refuse(error) {
+        this.#refusal ??= { error };
+        throw this.#refusal.error;
+    }
+    #invoke(operation, name) {
+        this.rethrowRefusal();
+        try {
+            const result = operation();
+            assertSynchronousCallbackResult(result, name);
+        }
+        catch (error) {
+            this.refuse(error);
+        }
+    }
+    assert() {
+        this.#invoke(() => this.#assertion?.(), "assertBeforeMutation");
+    }
+    destination(state, path, identity) {
+        if (state === "writing") {
+            if (this.#writingReported)
+                return;
+            this.#writingReported = true;
+        }
+        this.#invoke(() => this.#observer?.(Object.freeze({
+            state, path, dev: identity.dev, ino: identity.ino,
+        })), "onDestinationState");
+    }
+    removed(path) {
+        this.#invoke(() => this.#observer?.(Object.freeze({ state: "removed", path })), "onDestinationState");
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/replace-file-rename-policy.d.ts

@@ -0,0 +1,5 @@
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
+export declare function validateRenameIdentity(policy: RenameIdentityPolicy | undefined): void;
+export declare function atomicExpectedContentHash(policy: RenameIdentityPolicy | undefined, content: string | Uint8Array): string | undefined;
+export declare function withAtomicRenameIdentityLock<T>(filePath: string, fn: () => Promise<T>): Promise<T>;
+export declare function withAtomicRenameIdentityLockSync<T>(filePath: string, fn: () => T): T;

package/node_modules/@openclaw/fs-safe/dist/replace-file-rename-policy.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+import { withFileLock, withFileLockSync } from "./file-lock.js";
+import { sha256Hex } from "./file-identity.js";
+export function validateRenameIdentity(policy) {
+    if (policy !== undefined && policy !== "strict" && policy !== "verify-content-with-lock") {
+        throw new RangeError("renameIdentity must be strict or verify-content-with-lock");
+    }
+}
+export function atomicExpectedContentHash(policy, content) {
+    if (policy !== "verify-content-with-lock")
+        return undefined;
+    return sha256Hex(typeof content === "string" ? content : Buffer.from(content));
+}
+function lockOptions(filePath) {
+    const resolved = path.resolve(filePath);
+    return {
+        managerKey: `fs-safe.atomic:${resolved}`,
+        lockPath: path.join(path.dirname(resolved), `.fs-safe-atomic-${sha256Hex(resolved)}.lock`),
+        staleMs: 30_000,
+        timeoutMs: 5_000,
+        payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
+        retry: { retries: 5, minTimeout: 100, maxTimeout: 2_000, factor: 2 },
+    };
+}
+export async function withAtomicRenameIdentityLock(filePath, fn) {
+    return await withFileLock(filePath, lockOptions(filePath), fn);
+}
+export function withAtomicRenameIdentityLockSync(filePath, fn) {
+    return withFileLockSync(filePath, lockOptions(filePath), fn);
+}

package/node_modules/@openclaw/fs-safe/dist/replace-file-temp-owner.d.ts

@@ -0,0 +1,49 @@
+import syncFs, { type BigIntStats } from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+import { type TempPathRegistration } from "./temp-cleanup.js";
+type AsyncOwnerFileSystem = Pick<typeof fs, "lstat" | "open" | "unlink">;
+type SyncOwnerFileSystem = Pick<typeof syncFs, "closeSync" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "unlinkSync">;
+export type AtomicTempFailure = Readonly<{
+    error: unknown;
+}>;
+export declare function removePathIfIdentityUnchanged(targetPath: string, identity: Pick<BigIntStats, "dev" | "ino">): Promise<void>;
+declare class AtomicTempOwner<Resource> {
+    readonly pathname: string;
+    protected resource: Resource | undefined;
+    protected recordedIdentity: BigIntStats | undefined;
+    protected exists: boolean;
+    protected unregister: TempPathRegistration;
+    constructor(pathname: string);
+    start(): void;
+    readonly onIdentity: (identity: BigIntStats) => void;
+    get identity(): BigIntStats;
+    markRenamed(): void;
+    protected takeResource(): Resource | undefined;
+}
+export declare class AsyncAtomicTempOwner extends AtomicTempOwner<FileHandle> {
+    adopt(temp: {
+        handle: FileHandle;
+        identity: BigIntStats;
+    }): void;
+    assertCurrent(fsModule: AsyncOwnerFileSystem, pathname?: string): Promise<void>;
+    assertPublished(fsModule: AsyncOwnerFileSystem, pathname: string, expectedHash?: string, onVerified?: (identity: BigIntStats) => void): Promise<void>;
+    finish(params: {
+        fsModule: AsyncOwnerFileSystem;
+        originalFailure?: AtomicTempFailure;
+        throwOnCleanupError: boolean;
+    }): Promise<void>;
+}
+export declare class SyncAtomicTempOwner extends AtomicTempOwner<number> {
+    adopt(temp: {
+        fd: number;
+        identity: BigIntStats;
+    }): void;
+    assertCurrent(fsModule: SyncOwnerFileSystem, pathname?: string): void;
+    assertPublished(fsModule: SyncOwnerFileSystem, pathname: string, expectedHash?: string, onVerified?: (identity: BigIntStats) => void): void;
+    finish(params: {
+        fsModule: SyncOwnerFileSystem;
+        originalFailure?: AtomicTempFailure;
+        throwOnCleanupError: boolean;
+    }): void;
+}
+export {};