@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -1,13 +1,14 @@
 import fsSync, {} from "node:fs";
-import fs from "node:fs/promises";
+import fs, {} from "node:fs/promises";
 import { assertAsyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { resolveOpenedFileRealPathForFd } from "./opened-realpath.js";
-import { assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path.js";
+import { assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError } from "./path.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { assertRootIdentityCurrent } from "./root-context.js";
 import { fileNotFoundError, hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
 export async function verifyAtomicWriteResult(params) {
     let needsPathOpen = false;
     const assertFile = (stat) => {
@@ -44,49 +45,46 @@ export async function verifyAtomicWriteResult(params) {
         return stat;
     };
     try {
-        // This descriptor remains owned by the writer, even when final mode forbids opens.
-        const stat = assertDescriptor();
-        assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
-        const { realPath } = await resolveOpenedFileRealPathForFd(params.fd, stat, params.targetPath);
-        assertPath(fsSync.statSync(realPath, { bigint: true }));
-        if (!isPathInside(params.root.rootWithSep, realPath)) {
-            throw outsideWorkspaceError();
-        }
-        await assertAsyncDirectoryGuard(params.parentGuard);
-        await assertRootIdentityCurrent(params.root);
-        // Recheck after canonical resolution and directory checks, including late links.
-        assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
-        assertDescriptor();
-        if (needsPathOpen) {
-            // A retained fd cannot prove that an opaque Windows pathname still names it.
-            // Reopen only for publication verification: the writer's exact identity is
-            // independent proof unavailable to ordinary readers. Never read any bytes.
-            assertNoUnsafeDeviceReadPath(params.targetPath);
-            const opened = await fs.open(params.targetPath, resolveReadOpenFlags()).catch((error) => {
-                if (isSymlinkOpenError(error)) {
-                    throw new FsSafeError("symlink", "symlink open blocked", { cause: error });
-                }
-                if (hasNodeErrorCode(error, "EISDIR")) {
-                    throw new FsSafeError("not-file", "not a file");
-                }
-                throw error;
-            });
-            try {
-                const reopenedStat = assertDescriptor(opened.fd);
+        let opened;
+        try {
+            while (true) {
+                // The original descriptor remains borrowed; only a verification reopen is owned here.
+                const fd = opened?.fd ?? params.fd;
+                const stat = assertDescriptor(fd);
                 assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
-                const { realPath: reopenedPath } = await resolveOpenedFileRealPathForFd(opened.fd, reopenedStat, params.targetPath);
-                assertPath(fsSync.statSync(reopenedPath, { bigint: true }));
-                if (!isPathInside(params.root.rootWithSep, reopenedPath)) {
+                const { realPath, stat: resolvedStat } = await resolveOpenedFileRealPathForFd(fd, stat, params.targetPath);
+                // Consume the resolver's observation only in this pass; the checks after
+                // the directory guards must still sample the current path and descriptor.
+                assertPath(resolvedStat);
+                if (!admitPathInsideRoot({
+                    rootPath: params.root.rootReal,
+                    candidatePath: realPath,
+                    rootIdentity: params.root.rootIdentity,
+                })) {
                     throw outsideWorkspaceError();
                 }
                 await assertAsyncDirectoryGuard(params.parentGuard);
                 await assertRootIdentityCurrent(params.root);
+                // Recheck after canonical resolution and directory checks, including late links.
                 assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
-                assertDescriptor(opened.fd);
+                assertDescriptor(fd);
+                if (opened || !needsPathOpen)
+                    break;
+                // Opaque Windows pathname identity needs one independent, read-free reopen.
+                assertNoUnsafeDeviceReadPath(params.targetPath);
+                opened = await fs.open(params.targetPath, resolveReadOpenFlags()).catch((error) => {
+                    if (isSymlinkOpenError(error)) {
+                        throw new FsSafeError("symlink", "symlink open blocked", { cause: error });
+                    }
+                    if (hasNodeErrorCode(error, "EISDIR"))
+                        throw new FsSafeError("not-file", "not a file");
+                    throw error;
+                });
             }
-            finally {
+        }
+        finally {
+            if (opened)
                 await opened.close().catch(() => undefined);
-            }
         }
     }
     catch (error) {

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

@@ -1,4 +1,2 @@
-export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, type DenyMutationPolicy, type HardlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCreateJsonOptions, type RootCreateOptions, type RootDefaults, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type SymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root-impl.js";
-export type { ContainmentGuarantee } from "./containment.js";
-export type { RootWalkDataEntry, RootWalkDataEntryKind, RootWalkDirectoryErrorBehavior, RootWalkEntry, RootWalkEntryFilter, RootWalkEntryFilterResult, RootWalkEntryKind, RootWalkLimitBehavior, RootWalkOptions, RootWalkSymlinkPolicy, } from "./root-walk.js";
-//# sourceMappingURL=root.d.ts.map
+export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, type Root, } from "./root-impl.js";
+export type * from "./root-public-types.js";

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

@@ -7,6 +7,5 @@ export declare function assertNoDriveRelativePathSegments(value: string, label:
 export declare function trimHyphenEdges(value: string): string;
 export declare function isSafePathSegment(segment: string, options?: SafePathSegmentOptions): boolean;
 export declare function assertSafePathSegment(segment: string, options?: SafePathSegmentOptions): string;
-export declare function sanitizeSafePathSegment(value: string, fallback: string, options?: SafePathSegmentOptions): string;
+export declare function sanitizeSafePathSegment(value: string): string | undefined;
 export declare function assertSafePathPrefix(prefix: string, options?: SafePathSegmentOptions): string;
-//# sourceMappingURL=safe-path-segment.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/safe-path-segment.js

@@ -4,12 +4,14 @@ const SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
 // Windows treats "C:name" as relative to the drive's current directory even
 // though path.win32.isAbsolute() reports false.
 const DRIVE_RELATIVE_PREFIX = /^[A-Za-z]:(?![\\/])/;
+// A forward slash ends the segment, so "C:/file" still contains the "C:" segment.
+const DRIVE_RELATIVE_SEGMENT = /(?:^|\/)[A-Za-z]:(?!\\)/;
 const HYPHEN_CHAR_CODE = 0x2d;
 export function isDriveRelativePath(value) {
     return DRIVE_RELATIVE_PREFIX.test(value);
 }
 export function assertNoDriveRelativePathSegments(value, label) {
-    if (value.split("/").some(isDriveRelativePath)) {
+    if (DRIVE_RELATIVE_SEGMENT.test(value)) {
         throw new FsSafeError("invalid-path", `${label} must not contain a drive letter`);
     }
     return value;
@@ -45,17 +47,14 @@ export function assertSafePathSegment(segment, options = {}) {
     }
     return segment;
 }
-export function sanitizeSafePathSegment(value, fallback, options = {}) {
+export function sanitizeSafePathSegment(value) {
     const sanitized = value
         .trim()
         .replace(/[\\/]+/g, "-")
         .replace(/\0/g, "")
         .replace(/[^A-Za-z0-9._-]+/g, "-");
     const trimmed = trimHyphenEdges(sanitized);
-    if (isSafePathSegment(trimmed, options)) {
-        return trimmed;
-    }
-    return assertSafePathSegment(fallback, { ...options, label: "fallback path segment" });
+    return isSafePathSegment(trimmed, { allowDotPrefix: true }) ? trimmed : undefined;
 }
 export function assertSafePathPrefix(prefix, options = {}) {
     // Prefixes are often derived from safe filenames. Normalize harmless

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

@@ -11,6 +11,7 @@ type SecretFileWriteParams = {
     content: string | Uint8Array;
     mode?: number;
     dirMode?: number;
+    durable?: boolean;
 };
 export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParams, "content">): Promise<{
     mode: number;
@@ -22,4 +23,3 @@ export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParam
 export declare function writeSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
 export declare function createSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
 export {};
-//# sourceMappingURL=secret-file.d.ts.map

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

@@ -1,76 +1,48 @@
 import fs, {} from "node:fs";
 import fsp from "node:fs/promises";
 import path from "node:path";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
 import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
 import { assertOwnedDirectory } from "./directory-mode-owner.js";
-import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
-import { resolveHomeRelativePath } from "./home-dir.js";
 import { openPinnedFileSync } from "./pinned-open.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
 import { ensureTrailingSep } from "./root-context.js";
 import { verifyAtomicWriteResult } from "./root-write-verification.js";
-import { assertSecretFilePreview, resolveSecretReadPolicy, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
+import { prepareSecretRead, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { serializePathWrite } from "./write-queue.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 export const PRIVATE_SECRET_DIR_MODE = 0o700;
 export const PRIVATE_SECRET_FILE_MODE = 0o600;
 export function readSecretFileSync(filePath, label, options = {}) {
-    const { resolvedPath, maxBytes } = resolveSecretReadPolicy(filePath, label, options);
-    function inspectInput(symlinkMessage) {
-        const stat = options.rejectSymlink
-            ? fs.lstatSync(resolvedPath, { bigint: true })
-            : fs.statSync(resolvedPath, { bigint: true });
-        if (options.rejectSymlink && stat.isSymbolicLink()) {
-            throw new FsSafeError("symlink", symlinkMessage);
-        }
-        return stat;
-    }
-    let previewStat;
-    try {
-        assertNoUnsafeDeviceReadPath(resolvedPath);
-        previewStat = inspectFileIdentitySync(() => inspectInput(`${label} file at ${resolvedPath} must not be a symlink.`));
-    }
-    catch (error) {
-        throw secretReadError(error instanceof FsSafeError ? error.code : secretPathErrorCode(error), "inspect", label, resolvedPath, error);
-    }
-    assertSecretFilePreview(previewStat, label, resolvedPath, maxBytes, options.rejectHardlinks !== false);
+    const { resolvedPath, maxBytes, rejectSymlink, rejectHardlinks, previewStat, inspectInput } = prepareSecretRead(filePath, label, options);
     const opened = openPinnedFileSync({
         filePath: resolvedPath,
-        rejectPathSymlink: options.rejectSymlink,
-        rejectHardlinks: options.rejectHardlinks !== false,
+        rejectPathSymlink: rejectSymlink,
+        rejectHardlinks,
     });
     if (!opened.ok) {
         throw secretReadError(opened.reason === "path" ? "not-found" : "path-mismatch", "read", label, resolvedPath, opened.reason === "validation" ? new Error("security validation failed") : opened.error);
     }
     let raw;
     try {
-        const openedIdentity = inspectFileIdentitySync(() => {
-            const stat = fs.fstatSync(opened.fd, { bigint: true });
-            if (!stat.isFile() || (options.rejectHardlinks !== false && stat.nlink > 1n)) {
-                throw new FsSafeError("path-mismatch", "security validation failed");
-            }
-            return stat;
-        }, previewStat);
-        inspectFileIdentitySync(() => {
-            const stat = fs.lstatSync(opened.path, { bigint: true });
-            if (!stat.isFile() || (options.rejectHardlinks !== false && stat.nlink > 1n)) {
-                throw new FsSafeError("path-mismatch", "security validation failed");
-            }
-            return stat;
-        }, openedIdentity);
+        // The pin already compared the descriptor and resolved name without yielding.
+        const openedIdentity = inspectFileIdentitySync(() => opened.identity, previewStat);
         inspectFileIdentitySync(() => inspectInput("secret path became a symlink"), openedIdentity);
         raw = readFileDescriptorBoundedSync(opened.fd, maxBytes).toString("utf8");
     }
     catch (error) {
+        try {
+            fs.closeSync(opened.fd);
+        }
+        catch { /* Preserve the read failure. */ }
         throw secretReadError(error instanceof FsSafeError ? error.code : "read-failed", "read", label, resolvedPath, error);
     }
-    finally {
-        fs.closeSync(opened.fd);
-    }
+    fs.closeSync(opened.fd);
     return trimSecretFileContent(raw, label, resolvedPath);
 }
 export function tryReadSecretFileSync(filePath, label, options = {}) {
@@ -151,8 +123,8 @@ async function inspectPrivateDirectory(directory, kind) {
     });
 }
 async function ensurePrivateDirectory(rootDir, targetDir, mode) {
-    const resolvedRoot = path.resolve(rootDir);
-    const resolvedTarget = path.resolve(targetDir);
+    const resolvedRoot = resolvePathPreservingWindowsRoot(rootDir);
+    const resolvedTarget = resolvePathPreservingWindowsRoot(targetDir);
     let rootStat = await inspectPrivateDirectory(resolvedRoot, "root").catch((error) => {
         if (error.code !== "ENOENT")
             throw error;
@@ -166,7 +138,7 @@ async function ensurePrivateDirectory(rootDir, targetDir, mode) {
         catch (error) {
             if (error.code !== "ENOENT")
                 throw error;
-            await fsp.mkdir(path.dirname(resolvedRoot), { recursive: true, mode });
+            await fsp.mkdir(recursiveMkdirPath(path.dirname(resolvedRoot)), { recursive: true, mode });
             createdRoot = await createPrivateDirectory(resolvedRoot, mode);
         }
         rootStat = await inspectPrivateDirectory(resolvedRoot, "root");
@@ -227,21 +199,42 @@ async function ensurePrivateDirectory(rootDir, targetDir, mode) {
     }
     return { rootGuard, parentGuard: targetGuard };
 }
+function snapshotSecretFileWriteParams(params, rootDir, filePath) {
+    return {
+        rootDir,
+        filePath,
+        content: params.content,
+        mode: params.mode,
+        dirMode: params.dirMode,
+        durable: params.durable,
+    };
+}
 async function secretFileWriteQueueKey(filePath) {
+    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
     try {
         return await canonicalPathFromExistingAncestor(filePath);
     }
-    catch {
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "invalid-path")
+            throw error;
         // Keep validation and its public error shape owned by the write path below.
-        return path.resolve(filePath);
+        const resolved = path.resolve(filePath);
+        assertNoWindowsPathAlias(resolved, "filesystem", "private secret path uses a Windows filesystem namespace alias");
+        return resolved;
     }
 }
 // Internal preparation for private writers and their pre-write locks; not lasting authorization.
 export async function prepareSecretFileWrite(params) {
+    const rootDir = params.rootDir;
+    const filePath = params.filePath;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
     const mode = params.mode ?? PRIVATE_SECRET_FILE_MODE;
     const dirMode = params.dirMode ?? PRIVATE_SECRET_DIR_MODE;
-    const resolvedRoot = path.resolve(params.rootDir);
-    const resolvedFile = path.resolve(params.filePath);
+    const resolvedRoot = resolvePathPreservingWindowsRoot(rootDir);
+    const resolvedFile = path.resolve(filePath);
+    assertNoWindowsPathAlias(resolvedRoot, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(resolvedFile, "filesystem", "private secret path uses a Windows filesystem namespace alias");
     assertPathWithinRoot(resolvedRoot, resolvedFile);
     for (const [kind, value] of [["file", mode], ["directory", dirMode]]) {
         if (!Number.isInteger(value) || value < 0 || value > 0o7777) {
@@ -253,8 +246,11 @@ export async function prepareSecretFileWrite(params) {
     await assertAsyncDirectoryGuard(rootGuard);
     await assertAsyncDirectoryGuard(parentGuard);
     assertRealPathWithinRoot(rootGuard.realPath, parentGuard.realPath);
+    assertNoWindowsPathAlias(rootGuard.realPath, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(parentGuard.realPath, "filesystem", "private secret parent uses a Windows filesystem namespace alias");
     const fileName = path.basename(resolvedFile);
     const finalFilePath = path.join(parentGuard.realPath, fileName);
+    assertNoWindowsPathAlias(finalFilePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
     return { mode, rootGuard, parentGuard, fileName, finalFilePath };
 }
 async function materializeSecretFileAtomic(params, createOnly) {
@@ -284,6 +280,8 @@ async function materializeSecretFileAtomic(params, createOnly) {
         basename: fileName,
         mkdir: false,
         mode,
+        verifyPosixMode: true,
+        sync: params.durable !== false,
         overwrite: !createOnly,
         input: { kind: "buffer", data: typeof params.content === "string" ? params.content : Buffer.from(params.content) },
         rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },
@@ -307,16 +305,26 @@ async function materializeSecretFileAtomic(params, createOnly) {
     });
 }
 export async function writeSecretFileAtomic(params) {
-    const canonicalPath = await secretFileWriteQueueKey(params.filePath);
+    const rootDir = params.rootDir;
+    const filePath = params.filePath;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
+    const ownedParams = snapshotSecretFileWriteParams(params, rootDir, filePath);
+    const canonicalPath = await secretFileWriteQueueKey(filePath);
     await serializePathWrite(canonicalPath, async () => {
-        await materializeSecretFileAtomic(params, false);
+        await materializeSecretFileAtomic(ownedParams, false);
     });
 }
 export async function createSecretFileAtomic(params) {
     try {
-        const canonicalPath = await secretFileWriteQueueKey(params.filePath);
+        const rootDir = params.rootDir;
+        const filePath = params.filePath;
+        assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+        assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
+        const ownedParams = snapshotSecretFileWriteParams(params, rootDir, filePath);
+        const canonicalPath = await secretFileWriteQueueKey(filePath);
         await serializePathWrite(canonicalPath, async () => {
-            await materializeSecretFileAtomic(params, true);
+            await materializeSecretFileAtomic(ownedParams, true);
         });
     }
     catch (error) {

package/node_modules/@openclaw/fs-safe/dist/secret-read-async.d.ts

@@ -1,4 +1,3 @@
 import { type SecretFileReadOptions } from "./secret-read-policy.js";
 export declare function readSecretFile(filePath: string, label: string, options?: SecretFileReadOptions): Promise<string>;
 export declare function tryReadSecretFile(filePath: string | undefined, label: string, options?: SecretFileReadOptions): Promise<string | undefined>;
-//# sourceMappingURL=secret-read-async.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/secret-read-async.js

@@ -4,49 +4,34 @@ import { readFileHandleBounded } from "./bounded-read.js";
 import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
-import { inspectFileIdentity } from "./strict-file-identity.js";
-import { assertSecretFilePreview, resolveSecretReadPolicy, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { prepareSecretRead, secretPathErrorCode, secretReadError, trimSecretFileContent, } from "./secret-read-policy.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export async function readSecretFile(filePath, label, options = {}) {
-    const { resolvedPath, maxBytes } = resolveSecretReadPolicy(filePath, label, options);
-    async function inspectInput(symlinkMessage) {
-        const stat = options.rejectSymlink
-            ? await fs.lstat(resolvedPath, { bigint: true })
-            : await fs.stat(resolvedPath, { bigint: true });
-        if (options.rejectSymlink && stat.isSymbolicLink()) {
-            throw new FsSafeError("symlink", symlinkMessage);
-        }
-        return stat;
-    }
-    let previewStat;
-    try {
-        assertNoUnsafeDeviceReadPath(resolvedPath);
-        previewStat = await inspectFileIdentity(() => inspectInput(`${label} file at ${resolvedPath} must not be a symlink.`));
-    }
-    catch (error) {
-        throw secretReadError(error instanceof FsSafeError ? error.code : secretPathErrorCode(error), "inspect", label, resolvedPath, error);
-    }
-    assertSecretFilePreview(previewStat, label, resolvedPath, maxBytes, options.rejectHardlinks !== false);
+    const { resolvedPath, maxBytes, rejectHardlinks, previewStat, inspectInput } = prepareSecretRead(filePath, label, options);
     let handle;
     let raw;
     try {
-        const realPath = await fs.realpath(resolvedPath);
+        const realPath = realpathSync.native(resolvedPath);
+        assertNoWindowsPathAlias(realPath, "filesystem", `${label} file path uses a Windows filesystem namespace alias`);
         assertNoUnsafeDeviceReadPath(realPath);
         handle = await fs.open(realPath, resolveReadOpenFlags());
         const openedHandle = handle;
-        const openedStat = await inspectFileIdentity(async () => {
-            const stat = await openedHandle.stat({ bigint: true });
-            if (!stat.isFile() || (options.rejectHardlinks !== false && stat.nlink > 1n)) {
+        const openedStat = inspectFileIdentitySync(() => {
+            const stat = fsSync.fstatSync(openedHandle.fd, { bigint: true });
+            if (!stat.isFile() || (rejectHardlinks && stat.nlink > 1n)) {
                 throw new FsSafeError("path-mismatch", "security validation failed");
             }
             return stat;
         }, previewStat);
-        await inspectFileIdentity(async () => {
-            const stat = await fs.lstat(realPath, { bigint: true });
+        inspectFileIdentitySync(() => {
+            const stat = fsSync.lstatSync(realPath, { bigint: true });
             if (!stat.isFile())
                 throw new FsSafeError("path-mismatch", "security validation failed");
             return stat;
         }, openedStat);
-        await inspectFileIdentity(() => inspectInput("secret path became a symlink"), openedStat);
+        inspectFileIdentitySync(() => inspectInput("secret path became a symlink"), openedStat);
         raw = (await readFileHandleBounded(handle, maxBytes)).toString("utf8");
     }
     catch (error) {

package/node_modules/@openclaw/fs-safe/dist/secret-read-policy.d.ts

@@ -1,4 +1,4 @@
-import type { BigIntStats } from "node:fs";
+import { type BigIntStats } from "node:fs";
 import { FsSafeError, type FsSafeErrorCode } from "./errors.js";
 export declare const DEFAULT_SECRET_FILE_MAX_BYTES: number;
 export type SecretFileReadOptions = {
@@ -10,8 +10,11 @@ export declare function secretPathErrorCode(error: unknown): FsSafeErrorCode;
 export declare function secretReadError(code: FsSafeErrorCode, action: "inspect" | "read", label: string, resolvedPath: string, error: unknown): FsSafeError;
 export declare function assertSecretFilePreview(stat: BigIntStats, label: string, resolvedPath: string, maxBytes: number, rejectHardlinks: boolean): void;
 export declare function trimSecretFileContent(raw: string, label: string, resolvedPath: string): string;
-export declare function resolveSecretReadPolicy(filePath: string, label: string, options: SecretFileReadOptions): {
+export declare function prepareSecretRead(filePath: string, label: string, options: SecretFileReadOptions): {
     resolvedPath: string;
     maxBytes: number;
+    rejectSymlink: boolean;
+    rejectHardlinks: boolean;
+    previewStat: BigIntStats;
+    inspectInput: (symlinkMessage: string) => BigIntStats;
 };
-//# sourceMappingURL=secret-read-policy.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/secret-read-policy.js

@@ -1,6 +1,10 @@
 import { normalizeMaxBytes } from "./byte-budget.js";
 import { resolveHomeRelativePath } from "./home-dir.js";
+import fs, {} from "node:fs";
+import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
 export function secretPathErrorCode(error) {
     const code = error.code;
@@ -28,13 +32,37 @@ export function trimSecretFileContent(raw, label, resolvedPath) {
     }
     return secret;
 }
-export function resolveSecretReadPolicy(filePath, label, options) {
-    const resolvedPath = resolveHomeRelativePath(filePath.trim());
+export function prepareSecretRead(filePath, label, options) {
+    const trimmedPath = filePath.trim();
+    assertNoWindowsPathAlias(trimmedPath, "filesystem", `${label} file path uses a Windows filesystem namespace alias`);
+    const resolvedPath = resolveHomeRelativePath(trimmedPath);
     if (!resolvedPath) {
         throw new FsSafeError("invalid-path", `${label} file path is empty.`, { cause: undefined });
     }
+    assertNoWindowsPathAlias(resolvedPath, "filesystem", `${label} file path uses a Windows filesystem namespace alias`);
     const maxBytes = normalizeMaxBytes(options.maxBytes, {
         defaultValue: DEFAULT_SECRET_FILE_MAX_BYTES,
     });
-    return { resolvedPath, maxBytes };
+    let rejectSymlink;
+    let previewStat;
+    try {
+        assertNoUnsafeDeviceReadPath(resolvedPath);
+        rejectSymlink = Boolean(options.rejectSymlink);
+        previewStat = inspectFileIdentitySync(() => inspectInput(`${label} file at ${resolvedPath} must not be a symlink.`));
+    }
+    catch (error) {
+        throw secretReadError(error instanceof FsSafeError ? error.code : secretPathErrorCode(error), "inspect", label, resolvedPath, error);
+    }
+    function inspectInput(symlinkMessage) {
+        const stat = rejectSymlink
+            ? fs.lstatSync(resolvedPath, { bigint: true })
+            : fs.statSync(resolvedPath, { bigint: true });
+        if (rejectSymlink && stat.isSymbolicLink()) {
+            throw new FsSafeError("symlink", symlinkMessage);
+        }
+        return stat;
+    }
+    const rejectHardlinks = options.rejectHardlinks !== false;
+    assertSecretFilePreview(previewStat, label, resolvedPath, maxBytes, rejectHardlinks);
+    return { resolvedPath, maxBytes, rejectSymlink, rejectHardlinks, previewStat, inspectInput };
 }

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

@@ -1,4 +1,3 @@
 export { createSecretFileAtomic, PRIVATE_SECRET_DIR_MODE, PRIVATE_SECRET_FILE_MODE, readSecretFileSync, tryReadSecretFileSync, writeSecretFileAtomic, } from "./secret-file.js";
 export { DEFAULT_SECRET_FILE_MAX_BYTES, type SecretFileReadOptions } from "./secret-read-policy.js";
 export { readSecretFile, tryReadSecretFile } from "./secret-read-async.js";
-//# sourceMappingURL=secret.d.ts.map

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

@@ -0,0 +1,10 @@
+import type { BigIntStats, Stats } from "node:fs";
+import type { PermissionCheck } from "./permissions.js";
+type ExactIdentity = Pick<BigIntStats, "dev" | "ino">;
+/** Both mechanisms inspect the same borrowed handle; the caller owns its lifetime. */
+export declare function inspectSecureWindowsFile(params: {
+    fd: number;
+    identity: ExactIdentity;
+    stat: Stats;
+}): Promise<PermissionCheck>;
+export {};

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

@@ -0,0 +1,88 @@
+import { FsSafeError } from "./errors.js";
+import { recordFileObservationFailure } from "./file-observation.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 { 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 permissionUnverified(message, cause) {
+    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
+}
+function identityMismatch() {
+    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
+    recordFileObservationFailure(error, "identity");
+    throw error;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function parseIdentity(value) {
+    if (typeof value !== "string")
+        identityMismatch();
+    const match = IDENTITY_RE.exec(value);
+    if (!match)
+        identityMismatch();
+    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) {
+        identityMismatch();
+    }
+    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

@@ -1,4 +1,4 @@
-import type { Stats } from "node:fs";
+import { type Stats } from "node:fs";
 import { type PermissionCheck, type PermissionCheckOptions } from "./permissions.js";
 export type SecureFileReadOptions = {
     filePath: string;
@@ -29,4 +29,3 @@ export type SecureFileReadResult = {
     permissions?: PermissionCheck;
 };
 export declare function readSecureFile(options: SecureFileReadOptions): Promise<SecureFileReadResult>;
-//# sourceMappingURL=secure-file.d.ts.map