@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,79 @@
+import { fileIdentityMismatchError } from "./strict-file-identity.js";
+import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
+import { inspectWindowsDescriptorCommand } from "./windows-security-command.js";
+import { unverified as permissionUnverified, validateSecureWindowsSecurityFacts } from "./windows-security-facts.js";
+const IDENTITY_RE = /^([0-9a-f]{8}):([0-9a-f]{16})$/;
+const TRUSTED_OWNER_CLASSES = new Set(["current-user", "system", "administrators"]);
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function parseIdentity(value) {
+    if (typeof value !== "string")
+        throw fileIdentityMismatchError();
+    const match = IDENTITY_RE.exec(value);
+    if (!match)
+        throw fileIdentityMismatchError();
+    return {
+        dev: BigInt(`0x${match[1]}`),
+        ino: BigInt(`0x${match[2]}`),
+    };
+}
+function inspectDescriptorResult(params, result, mechanism) {
+    if (!isRecord(result))
+        permissionUnverified("Windows descriptor ACL facts were malformed");
+    const observed = parseIdentity(result.identity);
+    if (observed.dev !== params.identity.dev || observed.ino !== params.identity.ino) {
+        throw fileIdentityMismatchError();
+    }
+    const facts = validateSecureWindowsSecurityFacts(result.security);
+    return {
+        ok: true,
+        isSymlink: false,
+        isDir: params.stat.isDirectory(),
+        mode: typeof params.stat.mode === "number" ? params.stat.mode : null,
+        bits: null,
+        source: "windows-acl",
+        worldWritable: facts.worldWritable,
+        groupWritable: facts.groupWritable,
+        worldReadable: facts.worldReadable,
+        groupReadable: facts.groupReadable,
+        ownerSid: facts.ownerSid,
+        ownerTrusted: TRUSTED_OWNER_CLASSES.has(facts.ownerClass),
+        aclSummary: `${mechanism} descriptor owner=${facts.ownerClass} world=` +
+            `${facts.worldReadable ? "r" : "-"}${facts.worldWritable ? "w" : "-"} ` +
+            `group=${facts.groupReadable ? "r" : "-"}${facts.groupWritable ? "w" : "-"}`,
+    };
+}
+/** Both mechanisms inspect the same borrowed handle; the caller owns its lifetime. */
+export async function inspectSecureWindowsFile(params) {
+    let native;
+    try {
+        native = getNativeBinding();
+    }
+    catch (cause) {
+        permissionUnverified("Windows descriptor ACL verification requires the matching native helper", cause);
+    }
+    const inspect = native?.inspectWindowsSecureFileHandle;
+    const nativeAvailable = typeof inspect === "function";
+    if (!nativeAvailable && getFsSafeNativeConfig().mode === "require") {
+        permissionUnverified("Windows descriptor ACL verification requires an up-to-date native helper");
+    }
+    if (!nativeAvailable) {
+        warnNativeFallback("windows-secure-file", "Windows descriptor ACL inspection uses a slower built-in system command.");
+    }
+    let result;
+    try {
+        if (nativeAvailable) {
+            result = inspect.call(native, params.fd);
+        }
+        else {
+            result = await inspectWindowsDescriptorCommand(params.fd);
+        }
+    }
+    catch (cause) {
+        permissionUnverified("Windows descriptor ACL verification failed", cause);
+    }
+    return inspectDescriptorResult(params, result, nativeAvailable ? "native" : "system-command");
+}

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

@@ -0,0 +1,31 @@
+import { type Stats } from "node:fs";
+import { type PermissionCheck, type PermissionCheckOptions } from "./permissions.js";
+export type SecureFileReadOptions = {
+    filePath: string;
+    label?: string;
+    trust?: SecureFileTrustOptions;
+    permissions?: SecureFilePermissionOptions;
+    inject?: SecureFileInjectOptions;
+    io?: SecureFileIoOptions;
+};
+export type SecureFileTrustOptions = {
+    trustedDirs?: string[];
+    allowSymlink?: boolean;
+    allowNetworkPath?: boolean;
+};
+export type SecureFilePermissionOptions = {
+    allowInsecure?: boolean;
+    allowReadableByOthers?: boolean;
+};
+export type SecureFileInjectOptions = PermissionCheckOptions;
+export type SecureFileIoOptions = {
+    maxBytes?: number;
+    timeoutMs?: number;
+};
+export type SecureFileReadResult = {
+    buffer: Buffer;
+    realPath: string;
+    stat: Stats;
+    permissions?: PermissionCheck;
+};
+export declare function readSecureFile(options: SecureFileReadOptions): Promise<SecureFileReadResult>;

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

@@ -0,0 +1,298 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readFileHandleBounded } from "./bounded-read.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
+import { resolveEffectiveUid } from "./effective-uid.js";
+import { FsSafeError } from "./errors.js";
+import { isWindowsDriveLetterPath, isWindowsNetworkPath } from "./local-file-access.js";
+import { isPathInside, isSymlinkOpenError } from "./path.js";
+import { formatPermissionErrorDetail } from "./permission-exec.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { realpathSync } from "./realpath.js";
+import { inspectPathPermissions, isGroupReadable, isGroupWritable, isWorldReadable, isWorldWritable, modeBits, } from "./permissions.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { inspectSecureWindowsFile } from "./secure-file-windows.js";
+import { scheduleTimeout } from "./timing.js";
+import { anchorWindowsDriveRelativePath, assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function snapshotTrustedDirs(dirs) {
+    if (dirs === undefined)
+        return undefined;
+    if (!Array.isArray(dirs)) {
+        throw new FsSafeError("invalid-path", "trustedDirs must be an array of path strings.");
+    }
+    const trustedDirs = [];
+    const length = dirs.length;
+    if (!Number.isSafeInteger(length) || length < 0 || length > 0xffff_ffff) {
+        throw new FsSafeError("invalid-path", "trustedDirs must have a valid array length.");
+    }
+    for (let index = 0; index < length; index += 1) {
+        if (!Object.hasOwn(dirs, index)) {
+            throw new FsSafeError("invalid-path", "trustedDirs must not contain sparse entries.");
+        }
+        const dir = dirs[index];
+        if (typeof dir !== "string" || dir.includes("\0")) {
+            throw new FsSafeError("invalid-path", "trustedDirs must contain only path strings without null bytes.");
+        }
+        // Admit the raw suffix before normalization can erase an alternate stream,
+        // while retaining Node's per-drive cwd semantics for D:credentials.
+        const anchored = anchorWindowsDriveRelativePath(dir);
+        assertNoWindowsPathAlias(anchored, "filesystem", "trusted directory uses a Windows filesystem namespace alias");
+        const resolved = resolvePathPreservingWindowsRoot(anchored);
+        assertNoWindowsPathAlias(resolved, "filesystem", "trusted directory uses a Windows filesystem namespace alias");
+        trustedDirs.push(resolved);
+    }
+    return trustedDirs;
+}
+function snapshotPermissionEnv(env) {
+    if (env === undefined)
+        return undefined;
+    const snapshot = { ...env };
+    // Windows command lookup first reads these exact names, even when inherited
+    // or non-enumerable, then considers only enumerable own case variants.
+    // Reuse copied values so enumerable getters are not invoked a second time.
+    if (!Object.hasOwn(snapshot, "SystemRoot"))
+        snapshot.SystemRoot = env.SystemRoot;
+    if (!Object.hasOwn(snapshot, "WINDIR"))
+        snapshot.WINDIR = env.WINDIR;
+    return snapshot;
+}
+function snapshotSecureFileOptions(options, io, maxBytes) {
+    const { filePath, label, trust, permissions, inject } = options;
+    const env = inject?.env;
+    return {
+        filePath,
+        label,
+        trust: {
+            trustedDirs: snapshotTrustedDirs(trust?.trustedDirs),
+            allowSymlink: trust?.allowSymlink,
+            allowNetworkPath: trust?.allowNetworkPath,
+        },
+        permissions: {
+            allowInsecure: permissions?.allowInsecure,
+            allowReadableByOthers: permissions?.allowReadableByOthers,
+        },
+        inject: {
+            platform: inject?.platform,
+            env: snapshotPermissionEnv(env),
+            exec: inject?.exec,
+        },
+        io: {
+            maxBytes,
+            timeoutMs: io?.timeoutMs,
+        },
+    };
+}
+function isAbsolutePathname(value) {
+    return (path.isAbsolute(value) ||
+        (process.platform === "win32" &&
+            (isWindowsDriveLetterPath(value, "win32") || isWindowsNetworkPath(value, "win32"))));
+}
+function label(options) {
+    return options.label ?? "Secure file";
+}
+function assertNotHardlinked(options, stat) {
+    if (stat.nlink > 1n) {
+        throw new FsSafeError("hardlink", `${label(options)} must not be hardlinked: ${options.filePath}`);
+    }
+}
+async function openSecureHandle(options, maxBytes) {
+    assertNoUnsafeDeviceReadPath(options.filePath);
+    if (isWindowsNetworkPath(options.filePath, "win32") && !options.trust?.allowNetworkPath) {
+        throw new FsSafeError("invalid-path", `${label(options)} must be a local absolute path.`);
+    }
+    if (!isAbsolutePathname(options.filePath)) {
+        throw new FsSafeError("invalid-path", `${label(options)} must be an absolute path.`);
+    }
+    let preStat;
+    try {
+        preStat = fsSync.lstatSync(options.filePath);
+    }
+    catch (err) {
+        throw new FsSafeError("not-found", `${label(options)} is not readable: ${options.filePath}`, {
+            cause: err,
+        });
+    }
+    if (preStat.isSymbolicLink()) {
+        if (!options.trust?.allowSymlink) {
+            throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
+        }
+    }
+    else if (!preStat.isFile()) {
+        throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
+    }
+    let handle;
+    try {
+        handle = await fs.open(options.filePath, resolveReadOpenFlags({
+            followSymlinks: options.trust?.allowSymlink === true,
+        }));
+    }
+    catch (err) {
+        if (isSymlinkOpenError(err)) {
+            throw new FsSafeError("symlink", `${label(options)} symlink open blocked`, { cause: err });
+        }
+        throw err;
+    }
+    try {
+        const openedStat = fsSync.fstatSync(handle.fd);
+        if (!openedStat.isFile()) {
+            throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
+        }
+        const openedIdentity = inspectFileIdentitySync(() => fsSync.fstatSync(handle.fd, { bigint: true }));
+        assertNotHardlinked(options, openedIdentity);
+        inspectFileIdentitySync(() => {
+            const pathStat = options.trust?.allowSymlink
+                ? fsSync.statSync(options.filePath, { bigint: true })
+                : fsSync.lstatSync(options.filePath, { bigint: true });
+            if (!options.trust?.allowSymlink && pathStat.isSymbolicLink()) {
+                throw new FsSafeError("symlink", `${label(options)} must not be a symlink: ${options.filePath}`);
+            }
+            assertNotHardlinked(options, pathStat);
+            return pathStat;
+        }, openedIdentity);
+        const realPath = realpathSync.native(options.filePath);
+        assertNoWindowsPathAlias(realPath, "filesystem", `${label(options)} resolved path uses a Windows filesystem namespace alias`);
+        inspectFileIdentitySync(() => {
+            const realPathStat = fsSync.statSync(realPath, { bigint: true });
+            assertNotHardlinked(options, realPathStat);
+            return realPathStat;
+        }, openedIdentity);
+        if (maxBytes !== undefined && openedStat.size > maxBytes) {
+            throw new FsSafeError("too-large", `${label(options)} exceeded maxBytes (${maxBytes}).`);
+        }
+        return { handle, identity: openedIdentity, pathStat: openedStat, realPath };
+    }
+    catch (err) {
+        await handle.close().catch(() => undefined);
+        throw err;
+    }
+}
+function assertTrustedDirs(options, realPath) {
+    if (!options.trust?.trustedDirs || options.trust.trustedDirs.length === 0) {
+        return;
+    }
+    const trusted = options.trust.trustedDirs.map((dir) => {
+        let realPath;
+        try {
+            realPath = realpathSync.native(dir);
+        }
+        catch {
+            return dir;
+        }
+        assertNoWindowsPathAlias(realPath, "filesystem", "trusted directory uses a Windows filesystem namespace alias");
+        return realPath;
+    });
+    if (!trusted.some((dir) => isPathInside(dir, realPath))) {
+        throw new FsSafeError("outside-workspace", `${label(options)} is outside trustedDirs: ${realPath}`);
+    }
+}
+function inspectOpenedPermissions(stat, platform) {
+    const bits = modeBits(typeof stat.mode === "number" ? stat.mode : null);
+    return {
+        ok: true,
+        isSymlink: false,
+        isDir: stat.isDirectory(),
+        mode: typeof stat.mode === "number" ? stat.mode : null,
+        bits,
+        source: platform === "win32" ? "unknown" : "posix",
+        worldWritable: isWorldWritable(bits),
+        groupWritable: isGroupWritable(bits),
+        worldReadable: isWorldReadable(bits),
+        groupReadable: isGroupReadable(bits),
+    };
+}
+async function assertSecurePermissions(options, opened, fd) {
+    const { pathStat: stat, realPath, identity } = opened;
+    if (options.permissions?.allowInsecure) {
+        return undefined;
+    }
+    const platform = options.inject?.platform ?? process.platform;
+    const permissions = platform === "win32"
+        ? process.platform === "win32"
+            ? await inspectSecureWindowsFile({ fd, identity, stat })
+            : await inspectPathPermissions(realPath, options.inject)
+        : inspectOpenedPermissions(stat, platform);
+    const reason = permissions.error ? `: ${formatPermissionErrorDetail(permissions.error)}` : "";
+    const diagnostics = {
+        ...(permissions.errorCause !== undefined ? { cause: permissions.errorCause } : {}),
+        ...(permissions.ownerError || permissions.errorDetail ? {
+            details: {
+                ...(permissions.ownerError ? { ownerError: formatPermissionErrorDetail(permissions.ownerError) } : {}),
+                ...permissions.errorDetail,
+            },
+        } : {}),
+    };
+    if (!permissions.ok) {
+        throw new FsSafeError("permission-unverified", `${label(options)} permissions could not be verified: ${realPath}${reason}`, diagnostics);
+    }
+    if (platform === "win32" && permissions.source === "unknown") {
+        throw new FsSafeError("permission-unverified", `${label(options)} ACL verification unavailable on Windows for ${realPath}${reason || "."}`, diagnostics);
+    }
+    if (platform === "win32" && permissions.ownerTrusted !== true) {
+        throw new FsSafeError(permissions.ownerTrusted === false ? "not-owned" : "permission-unverified", `${label(options)} owner could not be trusted on Windows: ${realPath}`);
+    }
+    const writableByOthers = permissions.worldWritable || permissions.groupWritable;
+    const readableByOthers = permissions.worldReadable || permissions.groupReadable;
+    if (writableByOthers || (!options.permissions?.allowReadableByOthers && readableByOthers)) {
+        throw new FsSafeError("insecure-permissions", `${label(options)} permissions are too open: ${realPath}`);
+    }
+    if (platform !== "win32") {
+        let uid;
+        try {
+            uid = resolveEffectiveUid();
+        }
+        catch (cause) {
+            throw new FsSafeError("permission-unverified", `${label(options)} owner identity could not be verified for the effective user: ${realPath}`, { cause });
+        }
+        if (uid === undefined || !Number.isSafeInteger(stat.uid) || stat.uid < 0) {
+            throw new FsSafeError("permission-unverified", `${label(options)} owner identity could not be verified for the effective user: ${realPath}`);
+        }
+        if (stat.uid !== uid) {
+            throw new FsSafeError("not-owned", `${label(options)} must be owned by the effective user (uid=${uid}): ${realPath}`);
+        }
+    }
+    return permissions;
+}
+async function readHandleWithTimeout(handle, timeoutMs, maxBytes) {
+    const read = () => maxBytes === undefined ? handle.readFile() : readFileHandleBounded(handle, maxBytes);
+    if (timeoutMs === undefined || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return await read();
+    }
+    let cancelTimeout;
+    try {
+        return await Promise.race([
+            read(),
+            new Promise((_resolve, reject) => {
+                cancelTimeout = scheduleTimeout(() => {
+                    void handle.close().catch(() => undefined);
+                    reject(new FsSafeError("timeout", `secure file read timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        cancelTimeout?.();
+    }
+}
+export async function readSecureFile(options) {
+    const io = options.io;
+    const maxBytes = normalizeMaxBytes(io?.maxBytes);
+    options = snapshotSecureFileOptions(options, io, maxBytes);
+    assertNoWindowsPathAlias(options.filePath, "filesystem", `${label(options)} path uses a Windows filesystem namespace alias`);
+    const opened = await openSecureHandle(options, maxBytes);
+    try {
+        assertTrustedDirs(options, opened.realPath);
+        const permissions = await assertSecurePermissions(options, opened, opened.handle.fd);
+        const buffer = await readHandleWithTimeout(opened.handle, options.io?.timeoutMs, maxBytes);
+        const finalIdentity = inspectFileIdentitySync(() => fsSync.fstatSync(opened.handle.fd, { bigint: true }), opened.identity);
+        if (!finalIdentity.isFile()) {
+            throw new FsSafeError("not-file", `${label(options)} must remain a file: ${options.filePath}`);
+        }
+        assertNotHardlinked(options, finalIdentity);
+        return { buffer, realPath: opened.realPath, stat: opened.pathStat, permissions };
+    }
+    finally {
+        await opened.handle.close().catch(() => undefined);
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/secure-temp-dir.d.ts

@@ -0,0 +1,29 @@
+import { type SecureTempRootDescriptorAdapter } from "./secure-temp-repair.js";
+export type { SecureTempRootDescriptorAdapter } from "./secure-temp-repair.js";
+type SecureDirStat = {
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    mode?: number | bigint;
+    uid?: number | bigint;
+};
+export type ResolveSecureTempRootOptions = {
+    accessSync?: (path: string, mode?: number) => void;
+    /** @deprecated Unused. Repairs require descriptor-bound chmod. */
+    chmodSync?: (path: string, mode: number) => void;
+    descriptor?: SecureTempRootDescriptorAdapter;
+    fallbackPrefix: string;
+    getuid?: () => number | undefined;
+    lstatSync?: (path: string) => SecureDirStat;
+    mkdirSync?: (path: string, opts: {
+        recursive: boolean;
+        mode?: number;
+    }) => void;
+    platform?: NodeJS.Platform;
+    preferredDir?: string;
+    skipPreferredOnWindows?: boolean;
+    tmpdir?: () => string;
+    unsafeFallbackLabel?: string;
+    warn?: (message: string) => void;
+    warningPrefix?: string;
+};
+export declare function resolveSecureTempRoot(options: ResolveSecureTempRootOptions): string;

package/node_modules/@openclaw/fs-safe/dist/secure-temp-dir.js

@@ -0,0 +1,176 @@
+import fs from "node:fs";
+import { tmpdir as getOsTmpDir } from "node:os";
+import path from "node:path";
+import { directoryEntryPath } from "./directory-entry-path.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { hasNodeErrorCode } from "./path.js";
+import { assertSafePathSegment } from "./safe-path-segment.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
+import { captureSecureTempRepairAdapter, repairSecureTempDirectory, secureTempDirectoryReceipt, } from "./secure-temp-repair.js";
+export function resolveSecureTempRoot(options) {
+    const { fallbackPrefix: prefix, accessSync: suppliedAccess, lstatSync: suppliedLstat, mkdirSync: suppliedMkdir, descriptor: suppliedDescriptor, getuid: suppliedGetuid, tmpdir: suppliedTmpdir, platform: suppliedPlatform, preferredDir, skipPreferredOnWindows, warn: suppliedWarn, warningPrefix: suppliedWarningPrefix, unsafeFallbackLabel: suppliedFallbackLabel, } = options;
+    const platform = suppliedPlatform ?? process.platform;
+    const windows = process.platform === "win32" || platform === "win32";
+    // A platform adapter cannot disable the host's Windows pathname policy.
+    const admissionPlatform = process.platform === "win32" ? process.platform : platform;
+    const capturedDescriptor = captureSecureTempRepairAdapter(suppliedDescriptor, suppliedAccess !== undefined || suppliedLstat !== undefined || suppliedMkdir !== undefined);
+    const descriptor = windows ? undefined : capturedDescriptor;
+    const hostLstat = fs.lstatSync;
+    const hostAccess = fs.accessSync;
+    const hostMkdir = fs.mkdirSync;
+    const hostGetuid = process.getuid;
+    const accessSync = suppliedAccess ?? (process.platform === "win32"
+        ? (candidate, mode) => hostAccess(pathForWindowsFilesystem(candidate), mode)
+        : hostAccess);
+    const lstatSync = descriptor
+        ? (candidate) => descriptor.lstatSync(candidate, { bigint: true })
+        : suppliedLstat ?? ((candidate) => windows
+            ? hostLstat(pathForWindowsFilesystem(candidate))
+            : hostLstat(candidate, { bigint: true }));
+    // Virtual observations cannot authorize host creation. A supplied mkdir hook
+    // is explicit authority; chmodSync is deprecated and deliberately not read.
+    const mkdirSync = suppliedMkdir ?? (suppliedLstat !== undefined || suppliedAccess !== undefined || suppliedDescriptor !== undefined
+        ? undefined
+        : (directory, mkdirOptions) => hostMkdir(recursiveMkdirPath(pathForWindowsFilesystem(directory)), mkdirOptions));
+    const warn = suppliedWarn ?? console.warn.bind(console);
+    const warningPrefix = suppliedWarningPrefix ?? "[fs-safe]";
+    const unsafeFallbackLabel = suppliedFallbackLabel ?? "secure temp dir";
+    const tmpdir = typeof suppliedTmpdir === "function" ? suppliedTmpdir : getOsTmpDir;
+    const getuid = suppliedGetuid ?? (() => {
+        try {
+            return typeof hostGetuid === "function" ? hostGetuid.call(process) : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    });
+    const fallbackPrefix = assertSafePathSegment(prefix, {
+        allowDotPrefix: true,
+        label: "fallback temp prefix",
+    });
+    const TMP_DIR_ACCESS_MODE = fs.constants.W_OK | fs.constants.X_OK;
+    const uid = getuid();
+    if (uid !== undefined && (!Number.isSafeInteger(uid) || uid < 0)) {
+        throw new Error("Secure temp directory user identity is invalid.");
+    }
+    if (preferredDir !== undefined) {
+        assertNoWindowsPathAlias(preferredDir, "filesystem", "preferred temp directory uses a Windows filesystem namespace alias", admissionPlatform);
+    }
+    const isSecureDirForUser = (st) => {
+        if (windows || uid === undefined)
+            return true;
+        const { uid: owner, mode } = st;
+        if (owner !== undefined && owner !== uid && owner !== BigInt(uid))
+            return false;
+        if (typeof mode === "bigint")
+            return mode >= 0n && (mode & 18n) === 0n;
+        return mode === undefined || (Number.isSafeInteger(mode) && mode >= 0 && (mode & 0o022) === 0);
+    };
+    const fallback = () => {
+        const base = tmpdir();
+        assertNoWindowsPathAlias(base, "filesystem", "system temp directory uses a Windows filesystem namespace alias", admissionPlatform);
+        const suffix = uid === undefined ? fallbackPrefix : `${fallbackPrefix}-${uid}`;
+        const joiner = platform === "win32" ? path.win32.join : path.join;
+        const fallbackPath = joiner(base, suffix);
+        assertNoWindowsPathAlias(fallbackPath, "filesystem", "fallback temp directory uses a Windows filesystem namespace alias", admissionPlatform);
+        return fallbackPath;
+    };
+    const resolveDirState = (candidatePath) => {
+        assertNoWindowsPathAlias(candidatePath, "filesystem", "temp directory uses a Windows filesystem namespace alias", admissionPlatform);
+        let candidate;
+        try {
+            candidate = lstatSync(candidatePath);
+        }
+        catch (error) {
+            return { kind: hasNodeErrorCode(error, "ENOENT") ? "missing" : "invalid", error };
+        }
+        let receipt;
+        try {
+            if (descriptor && uid !== undefined) {
+                receipt = secureTempDirectoryReceipt(candidate, uid);
+            }
+            if (receipt ? (receipt.mode & 18n) !== 0n :
+                candidate.isDirectory() !== true || candidate.isSymbolicLink() !== false || !isSecureDirForUser(candidate)) {
+                return { kind: "invalid", receipt };
+            }
+            accessSync(candidatePath, TMP_DIR_ACCESS_MODE);
+            return { kind: "available", receipt };
+        }
+        catch (error) {
+            return { kind: "invalid", receipt, error };
+        }
+    };
+    const tryRepair = (candidatePath, state, finalize = false) => {
+        assertNoWindowsPathAlias(candidatePath, "filesystem", "temp directory uses a Windows filesystem namespace alias", admissionPlatform);
+        if (!descriptor || uid === undefined || !state.receipt) {
+            return finalize ? { kind: "invalid", error: new Error("Secure temp descriptor finalization is unavailable.") } : state;
+        }
+        try {
+            repairSecureTempDirectory(candidatePath, state.receipt, uid, descriptor, () => accessSync(candidatePath, TMP_DIR_ACCESS_MODE), () => warn(`${warningPrefix} tightened permissions on temp dir: ${candidatePath}`), finalize);
+            return { kind: "available" };
+        }
+        catch (error) {
+            return { kind: "invalid", error };
+        }
+    };
+    const ensureTrustedFallbackDir = () => {
+        const fallbackPath = fallback();
+        const entryPath = directoryEntryPath(fallbackPath, windows ? "win32" : platform);
+        let state = resolveDirState(entryPath);
+        let finalize = false;
+        if (state.kind === "available")
+            return fallbackPath;
+        if (state.kind === "missing") {
+            try {
+                if (!mkdirSync)
+                    throw new Error("Secure temp creation requires an explicit filesystem adapter.");
+                const created = mkdirSync(entryPath, { recursive: true, mode: 0o700 });
+                finalize = !windows && (suppliedMkdir !== undefined || created !== undefined);
+            }
+            catch (cause) {
+                throw new Error(`Unable to create fallback ${unsafeFallbackLabel}: ${fallbackPath}`, { cause });
+            }
+            // A concurrent mkdir winner has no implicit ownership or mode authority.
+            state = resolveDirState(entryPath);
+            if (state.kind === "available" && !finalize)
+                return fallbackPath;
+        }
+        state = tryRepair(entryPath, state, finalize);
+        if (state.kind !== "available") {
+            throw new Error(`Unsafe fallback ${unsafeFallbackLabel}: ${fallbackPath}`, { cause: state.error });
+        }
+        return fallbackPath;
+    };
+    if (skipPreferredOnWindows === true && platform === "win32") {
+        return ensureTrustedFallbackDir();
+    }
+    if (!preferredDir) {
+        return ensureTrustedFallbackDir();
+    }
+    const entryPath = directoryEntryPath(preferredDir, windows ? "win32" : platform);
+    const existingPreferredState = resolveDirState(entryPath);
+    if (existingPreferredState.kind === "available") {
+        return preferredDir;
+    }
+    if (existingPreferredState.kind === "invalid") {
+        if (tryRepair(entryPath, existingPreferredState).kind === "available") {
+            return preferredDir;
+        }
+        return ensureTrustedFallbackDir();
+    }
+    let preferredAvailable = false;
+    try {
+        const preferredParentDir = (windows ? path.win32 : path).dirname(entryPath);
+        accessSync(preferredParentDir, TMP_DIR_ACCESS_MODE);
+        if (mkdirSync) {
+            const created = mkdirSync(entryPath, { recursive: true, mode: 0o700 });
+            const finalize = !windows && (suppliedMkdir !== undefined || created !== undefined);
+            const state = resolveDirState(entryPath);
+            preferredAvailable = (!finalize && state.kind === "available") || tryRepair(entryPath, state, finalize).kind === "available";
+        }
+    }
+    catch {
+        // A failed preferred path never relaxes fallback admission.
+    }
+    return preferredAvailable ? preferredDir : ensureTrustedFallbackDir();
+}

package/node_modules/@openclaw/fs-safe/dist/secure-temp-repair.d.ts

@@ -0,0 +1,34 @@
+import { type BigIntStats } from "node:fs";
+type ExactDirectoryStat = Pick<BigIntStats, "dev" | "ino" | "uid" | "mode" | "isDirectory" | "isSymbolicLink">;
+/** Complete, synchronous descriptor authority for secure-temp admission and repair. */
+export type SecureTempRootDescriptorAdapter = {
+    lstatSync(path: string, options: {
+        bigint: true;
+    }): ExactDirectoryStat;
+    fstatSync(fd: number, options: {
+        bigint: true;
+    }): ExactDirectoryStat;
+    openSync(path: string, flags: number): number;
+    fchmodSync(fd: number, mode: number): void;
+    closeSync(fd: number): void;
+    constants: {
+        O_RDONLY: number;
+        O_DIRECTORY: number;
+        O_NOFOLLOW: number;
+        O_NONBLOCK: number;
+    };
+};
+export type SecureTempDirectoryReceipt = Readonly<{
+    dev: bigint;
+    ino: bigint;
+    uid: bigint;
+    mode: bigint;
+}>;
+export type SecureTempRepairAdapter = Omit<SecureTempRootDescriptorAdapter, "constants"> & {
+    flags: number;
+};
+export declare function captureSecureTempRepairAdapter(supplied: SecureTempRootDescriptorAdapter | undefined, hasLegacyFsHooks: boolean): SecureTempRepairAdapter | undefined;
+export declare function secureTempDirectoryReceipt(stat: ExactDirectoryStat, uid: number): SecureTempDirectoryReceipt;
+/** No pathname chmod, search-only descriptors, procfs, or reopening fallback. */
+export declare function repairSecureTempDirectory(candidate: string, expected: SecureTempDirectoryReceipt, uid: number, adapter: SecureTempRepairAdapter, access: () => void, repaired: () => void, finalize?: boolean): void;
+export {};