@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -1,15 +1,89 @@
+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 { inspectFileIdentity } from "./strict-file-identity.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" &&
@@ -18,6 +92,11 @@ function isAbsolutePathname(value) {
 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) {
@@ -26,11 +105,15 @@ async function openSecureHandle(options, maxBytes) {
     if (!isAbsolutePathname(options.filePath)) {
         throw new FsSafeError("invalid-path", `${label(options)} must be an absolute path.`);
     }
-    const preStat = await fs.lstat(options.filePath).catch((err) => {
+    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}`);
@@ -52,40 +135,54 @@ async function openSecureHandle(options, maxBytes) {
         throw err;
     }
     try {
-        const openedStat = await handle.stat();
+        const openedStat = fsSync.fstatSync(handle.fd);
         if (!openedStat.isFile()) {
             throw new FsSafeError("not-file", `${label(options)} must be a file: ${options.filePath}`);
         }
-        const openedIdentity = await inspectFileIdentity(() => handle.stat({ bigint: true }));
-        await inspectFileIdentity(async () => {
+        const openedIdentity = inspectFileIdentitySync(() => fsSync.fstatSync(handle.fd, { bigint: true }));
+        assertNotHardlinked(options, openedIdentity);
+        inspectFileIdentitySync(() => {
             const pathStat = options.trust?.allowSymlink
-                ? await fs.stat(options.filePath, { bigint: true })
-                : await fs.lstat(options.filePath, { bigint: true });
+                ? 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 = await fs.realpath(options.filePath);
-        await inspectFileIdentity(() => fs.stat(realPath, { bigint: true }), 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, pathStat: openedStat, realPath };
+        return { handle, identity: openedIdentity, pathStat: openedStat, realPath };
     }
     catch (err) {
         await handle.close().catch(() => undefined);
         throw err;
     }
 }
-async function assertTrustedDirs(options, realPath) {
+function assertTrustedDirs(options, realPath) {
     if (!options.trust?.trustedDirs || options.trust.trustedDirs.length === 0) {
         return;
     }
-    const trusted = await Promise.all(options.trust.trustedDirs.map(async (dir) => {
-        const resolved = path.resolve(dir);
-        return await fs.realpath(resolved).catch(() => resolved);
-    }));
+    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}`);
     }
@@ -105,13 +202,15 @@ function inspectOpenedPermissions(stat, platform) {
         groupReadable: isGroupReadable(bits),
     };
 }
-async function assertSecurePermissions(options, stat, realPath) {
+async function assertSecurePermissions(options, stat, realPath, identity, fd) {
     if (options.permissions?.allowInsecure) {
         return undefined;
     }
     const platform = options.inject?.platform ?? process.platform;
     const permissions = platform === "win32"
-        ? await inspectPathPermissions(realPath, options.inject)
+        ? 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 = {
@@ -137,10 +236,19 @@ async function assertSecurePermissions(options, stat, realPath) {
     if (writableByOthers || (!options.permissions?.allowReadableByOthers && readableByOthers)) {
         throw new FsSafeError("insecure-permissions", `${label(options)} permissions are too open: ${realPath}`);
     }
-    if (platform !== "win32" && typeof process.getuid === "function" && stat.uid != null) {
-        const uid = process.getuid();
+    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 current user (uid=${uid}): ${realPath}`);
+            throw new FsSafeError("not-owned", `${label(options)} must be owned by the effective user (uid=${uid}): ${realPath}`);
         }
     }
     return permissions;
@@ -150,12 +258,12 @@ async function readHandleWithTimeout(handle, timeoutMs, maxBytes) {
     if (timeoutMs === undefined || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         return await read();
     }
-    let timeout;
+    let cancelTimeout;
     try {
         return await Promise.race([
             read(),
             new Promise((_resolve, reject) => {
-                timeout = setTimeout(() => {
+                cancelTimeout = scheduleTimeout(() => {
                     void handle.close().catch(() => undefined);
                     reject(new FsSafeError("timeout", `secure file read timed out after ${timeoutMs}ms`));
                 }, timeoutMs);
@@ -163,17 +271,24 @@ async function readHandleWithTimeout(handle, timeoutMs, maxBytes) {
         ]);
     }
     finally {
-        if (timeout)
-            clearTimeout(timeout);
+        cancelTimeout?.();
     }
 }
 export async function readSecureFile(options) {
-    const maxBytes = normalizeMaxBytes(options.io?.maxBytes);
+    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 {
-        await assertTrustedDirs(options, opened.realPath);
-        const permissions = await assertSecurePermissions(options, opened.pathStat, opened.realPath);
+        assertTrustedDirs(options, opened.realPath);
+        const permissions = await assertSecurePermissions(options, opened.pathStat, opened.realPath, opened.identity, 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 {

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

@@ -1,12 +1,16 @@
+import { type SecureTempRootDescriptorAdapter } from "./secure-temp-repair.js";
+export type { SecureTempRootDescriptorAdapter } from "./secure-temp-repair.js";
 type SecureDirStat = {
     isDirectory(): boolean;
     isSymbolicLink(): boolean;
-    mode?: number;
-    uid?: number;
+    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;
@@ -23,5 +27,3 @@ export type ResolveSecureTempRootOptions = {
     warningPrefix?: string;
 };
 export declare function resolveSecureTempRoot(options: ResolveSecureTempRootOptions): string;
-export {};
-//# sourceMappingURL=secure-temp-dir.d.ts.map

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

@@ -1,7 +1,11 @@
 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 { assertSafePathSegment } from "./safe-path-segment.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
+import { captureSecureTempRepairAdapter, repairSecureTempDirectory, secureTempDirectoryReceipt, } from "./secure-temp-repair.js";
 function isNodeErrorWithCode(err, code) {
     return (typeof err === "object" &&
         err !== null &&
@@ -9,152 +13,169 @@ function isNodeErrorWithCode(err, code) {
         err.code === code);
 }
 export function resolveSecureTempRoot(options) {
-    const fallbackPrefix = assertSafePathSegment(options.fallbackPrefix, {
+    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 accessSync = options.accessSync ?? fs.accessSync;
-    const chmodSync = options.chmodSync ?? fs.chmodSync;
-    const lstatSync = options.lstatSync ?? fs.lstatSync;
-    const mkdirSync = options.mkdirSync ?? fs.mkdirSync;
-    const warn = options.warn ?? ((message) => console.warn(message));
-    const warningPrefix = options.warningPrefix ?? "[fs-safe]";
-    const unsafeFallbackLabel = options.unsafeFallbackLabel ?? "secure temp dir";
-    const getuid = options.getuid ??
-        (() => {
-            try {
-                return typeof process.getuid === "function" ? process.getuid() : undefined;
-            }
-            catch {
-                return undefined;
-            }
-        });
-    const tmpdir = typeof options.tmpdir === "function" ? options.tmpdir : getOsTmpDir;
-    const platform = options.platform ?? process.platform;
     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 (uid === undefined) {
+        if (windows || uid === undefined)
             return true;
-        }
-        if (typeof st.uid === "number" && st.uid !== uid) {
+        const { uid: owner, mode } = st;
+        if (owner !== undefined && owner !== uid && owner !== BigInt(uid))
             return false;
-        }
-        if (typeof st.mode === "number" && (st.mode & 0o022) !== 0) {
-            return false;
-        }
-        return true;
+        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;
-        return joiner(base, suffix);
-    };
-    const isTrustedTmpDir = (st) => {
-        return st.isDirectory() && !st.isSymbolicLink() && isSecureDirForUser(st);
+        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 {
-            const candidate = lstatSync(candidatePath);
-            if (!isTrustedTmpDir(candidate)) {
-                return "invalid";
+            candidate = lstatSync(candidatePath);
+        }
+        catch (error) {
+            return { kind: isNodeErrorWithCode(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 "available";
+            return { kind: "available", receipt };
         }
-        catch (err) {
-            if (isNodeErrorWithCode(err, "ENOENT")) {
-                return "missing";
-            }
-            return "invalid";
+        catch (error) {
+            return { kind: "invalid", receipt, error };
         }
     };
-    const tryRepairWritableBits = (candidatePath) => {
+    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 {
-            const st = lstatSync(candidatePath);
-            if (!st.isDirectory() || st.isSymbolicLink()) {
-                return false;
-            }
-            if (uid !== undefined && typeof st.uid === "number" && st.uid !== uid) {
-                return false;
-            }
-            if (typeof st.mode !== "number") {
-                return false;
-            }
-            if ((st.mode & 0o022) === 0) {
-                return resolveDirState(candidatePath) === "available";
-            }
-            try {
-                chmodSync(candidatePath, 0o700);
-            }
-            catch (chmodErr) {
-                if (isNodeErrorWithCode(chmodErr, "EPERM") ||
-                    isNodeErrorWithCode(chmodErr, "EACCES") ||
-                    isNodeErrorWithCode(chmodErr, "ENOENT")) {
-                    return resolveDirState(candidatePath) === "available";
-                }
-                throw chmodErr;
-            }
-            warn(`${warningPrefix} tightened permissions on temp dir: ${candidatePath}`);
-            return resolveDirState(candidatePath) === "available";
+            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 {
-            return false;
+        catch (error) {
+            return { kind: "invalid", error };
         }
     };
     const ensureTrustedFallbackDir = () => {
         const fallbackPath = fallback();
-        const state = resolveDirState(fallbackPath);
-        if (state === "available") {
+        const entryPath = directoryEntryPath(fallbackPath, windows ? "win32" : platform);
+        let state = resolveDirState(entryPath);
+        let finalize = false;
+        if (state.kind === "available")
             return fallbackPath;
-        }
-        if (state === "invalid") {
-            if (tryRepairWritableBits(fallbackPath)) {
-                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);
             }
-            throw new Error(`Unsafe fallback ${unsafeFallbackLabel}: ${fallbackPath}`);
-        }
-        try {
-            mkdirSync(fallbackPath, { recursive: true, mode: 0o700 });
-            chmodSync(fallbackPath, 0o700);
-        }
-        catch {
-            throw new Error(`Unable to create fallback ${unsafeFallbackLabel}: ${fallbackPath}`);
+            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;
         }
-        if (resolveDirState(fallbackPath) !== "available" && !tryRepairWritableBits(fallbackPath)) {
-            throw new Error(`Unsafe fallback ${unsafeFallbackLabel}: ${fallbackPath}`);
+        state = tryRepair(entryPath, state, finalize);
+        if (state.kind !== "available") {
+            throw new Error(`Unsafe fallback ${unsafeFallbackLabel}: ${fallbackPath}`, { cause: state.error });
         }
         return fallbackPath;
     };
-    if (options.skipPreferredOnWindows === true && platform === "win32") {
+    if (skipPreferredOnWindows === true && platform === "win32") {
         return ensureTrustedFallbackDir();
     }
-    if (!options.preferredDir) {
+    if (!preferredDir) {
         return ensureTrustedFallbackDir();
     }
-    const existingPreferredState = resolveDirState(options.preferredDir);
-    if (existingPreferredState === "available") {
-        return options.preferredDir;
+    const entryPath = directoryEntryPath(preferredDir, windows ? "win32" : platform);
+    const existingPreferredState = resolveDirState(entryPath);
+    if (existingPreferredState.kind === "available") {
+        return preferredDir;
     }
-    if (existingPreferredState === "invalid") {
-        if (tryRepairWritableBits(options.preferredDir)) {
-            return options.preferredDir;
+    if (existingPreferredState.kind === "invalid") {
+        if (tryRepair(entryPath, existingPreferredState).kind === "available") {
+            return preferredDir;
         }
         return ensureTrustedFallbackDir();
     }
+    let preferredAvailable = false;
     try {
-        const preferredParentDir = path.dirname(options.preferredDir);
+        const preferredParentDir = (windows ? path.win32 : path).dirname(entryPath);
         accessSync(preferredParentDir, TMP_DIR_ACCESS_MODE);
-        mkdirSync(options.preferredDir, { recursive: true, mode: 0o700 });
-        chmodSync(options.preferredDir, 0o700);
-        if (resolveDirState(options.preferredDir) !== "available" &&
-            !tryRepairWritableBits(options.preferredDir)) {
-            return ensureTrustedFallbackDir();
+        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";
         }
-        return options.preferredDir;
     }
     catch {
-        return ensureTrustedFallbackDir();
+        // 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 {};