@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,22 @@
+function unavailable(cause) {
+    return new Error("Effective user identity is unavailable.", {
+        ...(cause === undefined ? {} : { cause }),
+    });
+}
+export function resolveEffectiveUid() {
+    const provider = process.geteuid;
+    if (typeof provider !== "function") {
+        throw unavailable();
+    }
+    let uid;
+    try {
+        uid = provider.call(process);
+    }
+    catch (cause) {
+        throw unavailable(cause);
+    }
+    if (!(typeof uid === "number" && Number.isSafeInteger(uid) && uid >= 0)) {
+        throw unavailable();
+    }
+    return uid;
+}

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

@@ -0,0 +1,2 @@
+export declare function formatErrorDetail(value: string): string;
+export declare function shortPath(value: string): string;

package/node_modules/@openclaw/fs-safe/dist/error-detail.js

@@ -0,0 +1,13 @@
+import os from "node:os";
+import path from "node:path";
+const UNSAFE_ERROR_DETAIL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/gu;
+export function formatErrorDetail(value) {
+    return value.replace(UNSAFE_ERROR_DETAIL_CHARACTERS, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+export function shortPath(value) {
+    const home = os.homedir();
+    const prefix = home.endsWith(path.sep) ? home : `${home}${path.sep}`;
+    const shortened = value === home ? "~"
+        : value.startsWith(prefix) ? `~${path.sep}${value.slice(prefix.length)}` : value;
+    return formatErrorDetail(shortened);
+}

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

@@ -0,0 +1,15 @@
+export type FsSafeErrorCode = (typeof OPERATIONAL_CODE_VALUES)[number] | "already-exists" | "denied-path" | "device-path" | "hardlink" | "invalid-path" | "insecure-permissions" | "not-file" | "not-owned" | "outside-workspace" | "path-alias" | "path-mismatch" | "secret-exists" | "store-reentrant-update" | "symlink" | "too-large";
+export type FsSafeErrorCategory = "policy" | "operational";
+export type FsSafeErrorDetails = Readonly<Record<string, unknown>>;
+declare const OPERATIONAL_CODE_VALUES: readonly ["helper-failed", "helper-unavailable", "not-empty", "not-found", "not-removable", "permission-unverified", "read-failed", "timeout", "unsupported-platform"];
+export declare function categorizeFsSafeError(code: FsSafeErrorCode): FsSafeErrorCategory;
+export declare class FsSafeError extends Error {
+    readonly code: FsSafeErrorCode;
+    readonly category: FsSafeErrorCategory;
+    readonly details?: FsSafeErrorDetails;
+    constructor(code: FsSafeErrorCode, message: string, options?: {
+        cause?: unknown;
+        details?: FsSafeErrorDetails;
+    });
+}
+export {};

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

@@ -0,0 +1,27 @@
+const OPERATIONAL_CODE_VALUES = [
+    "helper-failed",
+    "helper-unavailable",
+    "not-empty",
+    "not-found",
+    "not-removable",
+    "permission-unverified",
+    "read-failed",
+    "timeout",
+    "unsupported-platform",
+];
+const OPERATIONAL_CODES = new Set(OPERATIONAL_CODE_VALUES);
+export function categorizeFsSafeError(code) {
+    return OPERATIONAL_CODES.has(code) ? "operational" : "policy";
+}
+export class FsSafeError extends Error {
+    code;
+    category;
+    details;
+    constructor(code, message, options = {}) {
+        super(message, options);
+        this.name = "FsSafeError";
+        this.code = code;
+        this.category = categorizeFsSafeError(code);
+        this.details = options.details;
+    }
+}

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

@@ -0,0 +1,19 @@
+import { type BigIntStats } from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+export declare function readErrorCode(error: unknown): unknown;
+export declare function hasErrorCode(error: unknown, expected: string): boolean;
+type OwnedPathCleanupStatus = "removed" | "name-absent" | "preserved";
+export declare function removeOwnedPath(params: {
+    fsModule: Pick<typeof fs, "lstat" | "unlink">;
+    pathname: string;
+    identity?: BigIntStats;
+}): Promise<OwnedPathCleanupStatus>;
+export declare function cleanupPinnedFilePath(params: {
+    pathname: string;
+    handle: Pick<FileHandle, "fd">;
+    identity?: BigIntStats;
+    parentGuard: AnyAsyncDirectoryGuard;
+    throwOnCleanupError?: boolean;
+}): Promise<OwnedPathCleanupStatus>;
+export {};

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

@@ -0,0 +1,81 @@
+import syncFs, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { assertAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+export function readErrorCode(error) {
+    if ((typeof error !== "object" || error === null) && typeof error !== "function") {
+        return undefined;
+    }
+    try {
+        return Reflect.get(error, "code");
+    }
+    catch {
+        return undefined;
+    }
+}
+export function hasErrorCode(error, expected) {
+    return readErrorCode(error) === expected;
+}
+export async function removeOwnedPath(params) {
+    if (!params.identity)
+        return "preserved";
+    try {
+        const current = params.fsModule === fs
+            ? syncFs.lstatSync(params.pathname, { bigint: true })
+            : await params.fsModule.lstat(params.pathname, { bigint: true });
+        if (current.isSymbolicLink() ||
+            !current.isFile() ||
+            current.nlink !== 1n ||
+            !sameFileIdentityForCleanup(current, params.identity)) {
+            return "preserved";
+        }
+        await params.fsModule.unlink(params.pathname);
+        return "removed";
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT"))
+            return "name-absent";
+        throw error;
+    }
+}
+// Borrowed handle: the caller retains it until guarded cleanup finishes.
+export async function cleanupPinnedFilePath(params) {
+    if (!params.identity)
+        return "preserved";
+    try {
+        const guard = params.parentGuard;
+        if ([guard.stat.dev, guard.stat.ino].some((value) => typeof value === "number" && !Number.isSafeInteger(value)))
+            return "preserved";
+        await assertAsyncDirectoryGuard(guard);
+        const parent = syncFs.lstatSync(guard.dir, { bigint: true });
+        if (parent.isSymbolicLink() || !parent.isDirectory() ||
+            !sameFileIdentityForCleanup(parent, guard.stat))
+            return "preserved";
+        const opened = syncFs.fstatSync(params.handle.fd, { bigint: true });
+        if (!opened.isFile() || opened.nlink !== 1n ||
+            !sameFileIdentityForCleanup(opened, params.identity))
+            return "preserved";
+    }
+    catch (error) {
+        // Unverifiable authority must preserve the path and the original write failure.
+        if (params.throwOnCleanupError &&
+            !(error instanceof FsSafeError && error.category === "policy") &&
+            !hasErrorCode(error, "ENOENT") && !hasErrorCode(error, "ENOTDIR") &&
+            !hasErrorCode(error, "ELOOP"))
+            throw error;
+        return "preserved";
+    }
+    try {
+        return await removeOwnedPath({
+            fsModule: fs,
+            pathname: params.pathname,
+            identity: params.identity,
+        });
+    }
+    catch (error) {
+        if (params.throwOnCleanupError)
+            throw error;
+        return "preserved";
+    }
+}

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

@@ -0,0 +1,5 @@
+export type SameFileContentsOptions = {
+    maxBytes?: number;
+};
+/** Compares borrowed regular files from offset zero without moving or closing either descriptor. */
+export declare function sameFileContentsSync(leftFd: number, rightFd: number, options?: SameFileContentsOptions): boolean;

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

@@ -0,0 +1,40 @@
+import fs from "node:fs";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { readFileWindowFullySync } from "./positional-read.js";
+/** Compares borrowed regular files from offset zero without moving or closing either descriptor. */
+export function sameFileContentsSync(leftFd, rightFd, options = {}) {
+    const maxBytes = normalizeMaxBytes(options.maxBytes) ?? Infinity;
+    const limit = Math.min(maxBytes, Number.MAX_SAFE_INTEGER);
+    const tooLarge = () => new FsSafeError("too-large", `file comparison exceeds ${limit} bytes`);
+    for (const fd of [leftFd, rightFd]) {
+        const stat = fs.fstatSync(fd, { bigint: true });
+        if (!stat.isFile()) {
+            throw new FsSafeError("not-file", "file comparison requires regular-file descriptors");
+        }
+        if (stat.size > BigInt(limit))
+            throw tooLarge();
+    }
+    const left = Buffer.allocUnsafe(Math.min(1024 * 1024, Math.max(1, limit)));
+    const right = Buffer.allocUnsafe(left.length);
+    let position = 0;
+    while (true) {
+        const length = Math.min(left.length, limit - position);
+        if (length === 0) {
+            // Probe EOF at the limit without forming an unsafe exclusive window end.
+            const leftExtra = fs.readSync(leftFd, left, 0, 1, position);
+            const rightExtra = fs.readSync(rightFd, right, 0, 1, position);
+            if (leftExtra !== 0 || rightExtra !== 0)
+                throw tooLarge();
+            return true;
+        }
+        const leftRead = readFileWindowFullySync(leftFd, left.subarray(0, length), position);
+        const rightRead = readFileWindowFullySync(rightFd, right.subarray(0, length), position);
+        if (leftRead !== rightRead || !left.subarray(0, leftRead).equals(right.subarray(0, rightRead))) {
+            return false;
+        }
+        if (leftRead < length)
+            return true;
+        position += leftRead;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/file-handle-transfer.d.ts

@@ -0,0 +1,15 @@
+import type { FileHandle } from "node:fs/promises";
+export type CopyFileHandleOptions = {
+    maxBytes?: number;
+    signal?: AbortSignal;
+    onChunk?: (chunk: Uint8Array) => void;
+    assertBeforeMutation?: () => void;
+};
+/** Copies caller-owned regular-file descriptors without moving either cursor. */
+export declare function copyFileDescriptorSync(sourceFd: number, targetFd: number, options?: CopyFileHandleOptions): number;
+/** Copies caller-owned regular files from offset zero without moving either cursor. */
+export declare function copyFileHandle(source: FileHandle, target: FileHandle, options?: CopyFileHandleOptions): Promise<number>;
+export declare function transferFileHandle(source: FileHandle, target: FileHandle | number, options: CopyFileHandleOptions & {
+    sizeHint: number;
+    targetPosition?: number;
+}): Promise<number>;

package/node_modules/@openclaw/fs-safe/dist/file-handle-transfer.js

@@ -0,0 +1,190 @@
+import fs from "node:fs";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { FsSafeError } from "./errors.js";
+import { assertSynchronousCallbackResult, composeMutationAssertions, rethrowMutationAuthorityError, } from "./mutation-authority.js";
+import { writeAllToFile } from "./write-file-handle.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+const NO_CALLBACK_ARGUMENTS = Object.freeze([]);
+function createTransferBuffer(sizeHint, limit) {
+    return Buffer.allocUnsafe(Math.min(512 * 1024, Math.max(64 * 1024, sizeHint), limit + 1));
+}
+/** Copies caller-owned regular-file descriptors without moving either cursor. */
+export function copyFileDescriptorSync(sourceFd, targetFd, options = {}) {
+    const signal = options.signal;
+    signal?.throwIfAborted();
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const onChunk = options.onChunk;
+    const assertBeforeMutation = options.assertBeforeMutation;
+    const sourceStat = inspectFileIdentitySync(() => {
+        signal?.throwIfAborted();
+        return fs.fstatSync(sourceFd, { bigint: true });
+    });
+    if (!sourceStat.isFile())
+        throw new FsSafeError("not-file", "copy source descriptor must be a regular file");
+    if (maxBytes !== undefined && Number.isFinite(maxBytes) && sourceStat.size > BigInt(maxBytes)) {
+        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`);
+    }
+    const targetStat = inspectFileIdentitySync(() => {
+        signal?.throwIfAborted();
+        return fs.fstatSync(targetFd, { bigint: true });
+    });
+    if (!targetStat.isFile())
+        throw new FsSafeError("not-file", "copy target descriptor must be a regular file");
+    if (sourceStat.dev === targetStat.dev && sourceStat.ino === targetStat.ino) {
+        throw new FsSafeError("path-alias", "copy source and target descriptors refer to the same file");
+    }
+    const limit = maxBytes ?? Infinity;
+    const buffer = createTransferBuffer(Number(sourceStat.size), limit);
+    let position = 0;
+    while (true) {
+        signal?.throwIfAborted();
+        const bytesRead = fs.readSync(sourceFd, buffer, 0, Math.min(buffer.length, limit - position + 1), position);
+        if (bytesRead > limit - position) {
+            throw new FsSafeError("too-large", `file exceeds limit of ${limit} bytes`);
+        }
+        if (bytesRead === 0)
+            return position;
+        const chunk = buffer.subarray(0, bytesRead);
+        assertSynchronousCallbackResult(onChunk?.(chunk), "onChunk");
+        let offset = 0;
+        while (offset < bytesRead) {
+            signal?.throwIfAborted();
+            assertSynchronousCallbackResult(assertBeforeMutation?.(), "assertBeforeMutation");
+            signal?.throwIfAborted();
+            const written = fs.writeSync(targetFd, chunk, offset, bytesRead - offset, position + offset);
+            if (written <= 0)
+                throw new FsSafeError("helper-failed", "file write made no progress");
+            offset += written;
+        }
+        position += bytesRead;
+    }
+}
+function defineReceiverValue(receiver, key, value) {
+    Object.defineProperty(receiver, key, {
+        value, enumerable: true, writable: true, configurable: true,
+    });
+}
+function copyTransferReceiver(options, maxBytes, sizeHint, signal, onChunk, assertBeforeMutation) {
+    const receiver = {};
+    const spreadSource = Object(options);
+    // Preserve the former late object-spread boundary, including proxy traps and
+    // unrelated getter failures. Authority-bearing values stay on their early
+    // snapshots, while descriptors still run in original own-key order.
+    for (const key of Reflect.ownKeys(spreadSource)) {
+        if (!Object.getOwnPropertyDescriptor(spreadSource, key)?.enumerable)
+            continue;
+        let value;
+        switch (key) {
+            case "maxBytes":
+                value = maxBytes;
+                break;
+            case "signal":
+                value = signal;
+                break;
+            case "onChunk":
+                value = onChunk;
+                break;
+            case "assertBeforeMutation":
+                value = assertBeforeMutation;
+                break;
+            default: value = Reflect.get(spreadSource, key);
+        }
+        // Create a data property so an enumerable __proto__ key cannot alter the
+        // ordinary receiver prototype, matching object spread.
+        defineReceiverValue(receiver, key, value);
+    }
+    // Match the explicit fields that followed the former spread. Updating an
+    // existing key retains its original position; absent keys append in order.
+    defineReceiverValue(receiver, "maxBytes", maxBytes);
+    defineReceiverValue(receiver, "sizeHint", sizeHint);
+    defineReceiverValue(receiver, "targetPosition", 0);
+    defineReceiverValue(receiver, "assertBeforeMutation", assertBeforeMutation);
+    return receiver;
+}
+/** Copies caller-owned regular files from offset zero without moving either cursor. */
+export async function copyFileHandle(source, target, options = {}) {
+    // Snapshot caller-owned options before the first await. This preserves
+    // inherited/non-enumerable callbacks and prevents accessor mutation from
+    // replacing cancellation or mutation authority mid-transfer.
+    const signal = options.signal;
+    signal?.throwIfAborted();
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    const onChunk = options.onChunk;
+    const assertBeforeMutation = composeMutationAssertions(undefined, options.assertBeforeMutation);
+    const sourceStat = await inspectFileIdentity(() => {
+        signal?.throwIfAborted();
+        return source.stat({ bigint: true });
+    });
+    signal?.throwIfAborted();
+    if (!sourceStat.isFile())
+        throw new FsSafeError("not-file", "copy source handle must be a regular file");
+    if (maxBytes !== undefined && Number.isFinite(maxBytes) && sourceStat.size > BigInt(maxBytes)) {
+        throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes`);
+    }
+    const targetStat = await inspectFileIdentity(() => {
+        signal?.throwIfAborted();
+        return target.stat({ bigint: true });
+    });
+    signal?.throwIfAborted();
+    if (!targetStat.isFile())
+        throw new FsSafeError("not-file", "copy target handle must be a regular file");
+    if (sourceStat.dev === targetStat.dev && sourceStat.ino === targetStat.ino) {
+        throw new FsSafeError("path-alias", "copy source and target handles refer to the same file");
+    }
+    const sizeHint = Number(sourceStat.size);
+    const callbackThis = copyTransferReceiver(options, maxBytes, sizeHint, signal, onChunk, assertBeforeMutation);
+    const beforeWrite = () => {
+        signal?.throwIfAborted();
+        assertBeforeMutation?.();
+    };
+    return await transferFileHandleCore(source, target, sizeHint, maxBytes, 0, signal, onChunk, beforeWrite, callbackThis).catch(rethrowMutationAuthorityError);
+}
+// Root.copyIn supplies already-admitted identities and retains its owned target cursor.
+export function transferFileHandle(source, target, options) {
+    try {
+        const maxBytes = options.maxBytes;
+        const sizeHint = options.sizeHint;
+        const targetPosition = options.targetPosition;
+        const signal = options.signal;
+        const onChunk = options.onChunk;
+        const assertBeforeMutation = options.assertBeforeMutation;
+        const beforeWrite = signal === undefined && assertBeforeMutation === undefined
+            ? undefined
+            : () => {
+                signal?.throwIfAborted();
+                if (assertBeforeMutation) {
+                    Reflect.apply(assertBeforeMutation, options, NO_CALLBACK_ARGUMENTS);
+                }
+            };
+        return transferFileHandleCore(source, target, sizeHint, maxBytes, targetPosition, signal, onChunk, beforeWrite, options);
+    }
+    catch (error) {
+        // Keep the former async-function contract for synchronous option getters.
+        return Promise.reject(error);
+    }
+}
+async function transferFileHandleCore(source, target, sizeHint, maxBytes, targetPosition, signal, onChunk, beforeWrite, callbackThis) {
+    const limit = maxBytes ?? Infinity;
+    const buffer = createTransferBuffer(sizeHint, limit);
+    let position = 0;
+    while (true) {
+        signal?.throwIfAborted();
+        const { bytesRead } = await source.read(buffer, 0, Math.min(buffer.length, limit - position + 1), position);
+        signal?.throwIfAborted();
+        if (bytesRead > limit - position) {
+            throw new FsSafeError("too-large", `file exceeds limit of ${limit} bytes`);
+        }
+        if (bytesRead === 0)
+            return position;
+        const chunk = buffer.subarray(0, bytesRead);
+        if (onChunk) {
+            const returned = Function.prototype.call.call(onChunk, callbackThis, chunk);
+            assertSynchronousCallbackResult(returned, "onChunk");
+        }
+        await writeAllToFile(target, chunk, {
+            position: targetPosition === undefined ? undefined : targetPosition + position,
+            assertBeforeMutation: beforeWrite,
+        });
+        position += bytesRead;
+    }
+}

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

@@ -0,0 +1,16 @@
+import type { FileHandle } from "node:fs/promises";
+import { type NativeBinding } from "./native.js";
+export type Sha256FileInput = string | FileHandle;
+export type Sha256FileSyncInput = string | number;
+export type Sha256FileOptions = {
+    maxBytes?: number;
+    signal?: AbortSignal;
+};
+export type Sha256FileResult = {
+    bytes: number;
+    digest: string;
+};
+export declare function hashFileHandle(handle: FileHandle, native?: NativeBinding | undefined, { maxBytes, signal }?: Sha256FileOptions): Promise<Sha256FileResult>;
+export declare function sha256File(input: Sha256FileInput, options?: Sha256FileOptions): Promise<Sha256FileResult>;
+/** Hash synchronously from offset zero, retaining ownership and position of a borrowed fd. */
+export declare function sha256FileSync(input: Sha256FileSyncInput, options?: Sha256FileOptions): Sha256FileResult;