@openclaw/feishu 2026.9.6 → 2026.9.8

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

@@ -0,0 +1,12 @@
+export type SafePathSegmentOptions = {
+    allowDotPrefix?: boolean;
+    label?: string;
+};
+export declare function isDriveRelativePath(value: string): boolean;
+export declare function assertNoDriveRelativePathSegments(value: string, label: string): string;
+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 normalizeSafePathSegment(value: string): string;
+export declare function sanitizeSafePathSegment(value: string): string | undefined;
+export declare function assertSafePathPrefix(prefix: string, options?: SafePathSegmentOptions): string;

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

@@ -0,0 +1,80 @@
+import { isWindowsReservedDeviceName } from "./device-path.js";
+import { FsSafeError } from "./errors.js";
+const SAFE_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+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 (DRIVE_RELATIVE_SEGMENT.test(value)) {
+        throw new FsSafeError("invalid-path", `${label} must not contain a drive letter`);
+    }
+    return value;
+}
+export function trimHyphenEdges(value) {
+    let start = 0;
+    let end = value.length;
+    while (start < end && value.charCodeAt(start) === HYPHEN_CHAR_CODE) {
+        start += 1;
+    }
+    while (end > start && value.charCodeAt(end - 1) === HYPHEN_CHAR_CODE) {
+        end -= 1;
+    }
+    return start === 0 && end === value.length ? value : value.slice(start, end);
+}
+export function isSafePathSegment(segment, options = {}) {
+    return (segment !== "" &&
+        segment !== "." &&
+        segment !== ".." &&
+        !segment.includes("/") &&
+        !segment.includes("\\") &&
+        !segment.includes("\0") &&
+        // Segments are portable identifiers: CON.json and CON.<pid>.tmp name devices on Windows.
+        !isWindowsReservedDeviceName(segment) &&
+        (options.allowDotPrefix === true || !segment.startsWith(".")) &&
+        (options.allowDotPrefix === true
+            ? SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN.test(segment)
+            : SAFE_PATH_SEGMENT_PATTERN.test(segment)));
+}
+export function assertSafePathSegment(segment, options = {}) {
+    // Validate the exact value callers will later join into paths; trimming here
+    // would let whitespace-padded ids pass and then be used verbatim.
+    if (!isSafePathSegment(segment, options)) {
+        throw new FsSafeError("invalid-path", `${options.label ?? "path segment"} must be a safe path segment`);
+    }
+    return segment;
+}
+export function normalizeSafePathSegment(value) {
+    const sanitized = value
+        .trim()
+        .replace(/[\\/]+/g, "-")
+        .replace(/\0/g, "")
+        .replace(/[^A-Za-z0-9._-]+/g, "-");
+    return trimHyphenEdges(sanitized);
+}
+export function sanitizeSafePathSegment(value) {
+    const trimmed = normalizeSafePathSegment(value);
+    return isSafePathSegment(trimmed, { allowDotPrefix: true }) ? trimmed : undefined;
+}
+export function assertSafePathPrefix(prefix, options = {}) {
+    // Prefixes are often derived from safe filenames. Normalize harmless
+    // filename characters first, but still reject real path-control bytes.
+    if (prefix.includes("/") || prefix.includes("\\") || prefix.includes("\0")) {
+        return assertSafePathSegment(prefix, {
+            allowDotPrefix: true,
+            ...options,
+            label: options.label ?? "path prefix",
+        });
+    }
+    return assertSafePathSegment(prefix.replace(/[^A-Za-z0-9._-]+/g, "-"), {
+        allowDotPrefix: true,
+        ...options,
+        label: options.label ?? "path prefix",
+    });
+}

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

@@ -0,0 +1,29 @@
+import { type BigIntStats } from "node:fs";
+import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import { type SecretFileReadOptions } from "./secret-read-policy.js";
+export declare const PRIVATE_SECRET_DIR_MODE = 448;
+export declare const PRIVATE_SECRET_FILE_MODE = 384;
+export declare function readSecretFileSync(filePath: string, label: string, options?: SecretFileReadOptions): string;
+export declare function tryReadSecretFileSync(filePath: string | undefined, label: string, options?: SecretFileReadOptions): string | undefined;
+type SecretFileWriteParams = {
+    rootDir: string;
+    filePath: string;
+    content: string | Uint8Array;
+    mode?: number;
+    dirMode?: number;
+    durable?: boolean;
+};
+type SecretFileCreateParams = Omit<SecretFileWriteParams, "durable"> & {
+    /** "file" requires file synchronization; directory synchronization remains best effort. */
+    durable?: boolean | "file";
+};
+export declare function prepareSecretFileWrite(params: Pick<SecretFileWriteParams, "rootDir" | "filePath" | "mode" | "dirMode">): Promise<{
+    mode: number;
+    rootGuard: AsyncDirectoryGuard<BigIntStats>;
+    parentGuard: AsyncDirectoryGuard<BigIntStats>;
+    fileName: string;
+    finalFilePath: string;
+}>;
+export declare function writeSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
+export declare function createSecretFileAtomic(params: SecretFileCreateParams): Promise<void>;
+export {};

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

@@ -0,0 +1,333 @@
+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, assertOwnedDirectory } from "./directory-mode-node.js";
+import { FsSafeError } from "./errors.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 { 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, rejectSymlink, rejectHardlinks, previewStat, inspectInput } = prepareSecretRead(filePath, label, options);
+    const opened = openPinnedFileSync({
+        filePath: resolvedPath,
+        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 {
+        // 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);
+    }
+    fs.closeSync(opened.fd);
+    return trimSecretFileContent(raw, label, resolvedPath);
+}
+export function tryReadSecretFileSync(filePath, label, options = {}) {
+    if (!filePath?.trim()) {
+        return undefined;
+    }
+    try {
+        return readSecretFileSync(filePath, label, options);
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "not-found")
+            return undefined;
+        throw error;
+    }
+}
+function isRelativeEscape(relativePath) {
+    return relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath);
+}
+function assertPathWithinRoot(rootDir, targetPath) {
+    const relative = path.relative(rootDir, targetPath);
+    if (!relative || isRelativeEscape(relative)) {
+        throw new Error(`Private secret path must stay under ${rootDir}.`);
+    }
+}
+function assertRealPathWithinRoot(rootDir, targetPath) {
+    const relative = path.relative(rootDir, targetPath);
+    if (isRelativeEscape(relative)) {
+        throw new Error(`Private secret path must stay under ${rootDir}.`);
+    }
+}
+async function createPrivateDirectory(directory, mode) {
+    try {
+        await fsp.mkdir(directory, { mode });
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+}
+async function enforcePrivateDirectoryMode(params) {
+    if (process.platform === "win32")
+        return;
+    const stat = await inspectDirectoryIdentity(params.realPath, params.identity);
+    if (!params.created) {
+        const actualMode = Number(stat.mode & 4095n);
+        if (actualMode !== params.mode) {
+            throw new FsSafeError("insecure-permissions", `Private secret directory ${JSON.stringify(params.realPath)} has insecure permissions ${actualMode.toString(8)}.`);
+        }
+        return;
+    }
+    const ownerUid = process.geteuid?.();
+    if (ownerUid === undefined) {
+        throw new FsSafeError("helper-unavailable", "secret directory initialization requires owner identity");
+    }
+    const owner = await pinNodeDirectoryForMode(params.realPath, {
+        expectedIdentity: params.identity,
+        ownerUid,
+    });
+    try {
+        await owner.apply(params.mode, { beforeChmod: params.beforeChmod });
+    }
+    finally {
+        await owner.close();
+    }
+}
+async function inspectPrivateDirectory(directory, kind) {
+    return await inspectFileIdentity(async () => {
+        const stat = fs.lstatSync(directory, { bigint: true });
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Private secret ${kind} ${directory} must not be a symlink.`);
+        }
+        if (!stat.isDirectory()) {
+            throw new Error(`Private secret ${kind} ${directory} must be a directory.`);
+        }
+        return stat;
+    });
+}
+async function ensurePrivateDirectory(rootDir, targetDir, mode) {
+    const resolvedRoot = resolvePathPreservingWindowsRoot(rootDir);
+    const resolvedTarget = resolvePathPreservingWindowsRoot(targetDir);
+    let rootStat = await inspectPrivateDirectory(resolvedRoot, "root").catch((error) => {
+        if (error.code !== "ENOENT")
+            throw error;
+        return undefined;
+    });
+    let createdRoot = false;
+    if (!rootStat) {
+        try {
+            createdRoot = await createPrivateDirectory(resolvedRoot, mode);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            await fsp.mkdir(recursiveMkdirPath(path.dirname(resolvedRoot)), { recursive: true, mode });
+            createdRoot = await createPrivateDirectory(resolvedRoot, mode);
+        }
+        rootStat = await inspectPrivateDirectory(resolvedRoot, "root");
+    }
+    const rootGuard = await createAsyncDirectoryGuard(resolvedRoot, { bigint: true });
+    assertOwnedDirectory(rootStat, rootGuard.stat);
+    await enforcePrivateDirectoryMode({
+        realPath: rootGuard.realPath, identity: rootStat, mode, created: createdRoot,
+        beforeChmod: () => assertAsyncDirectoryGuard(rootGuard),
+    });
+    await assertAsyncDirectoryGuard(rootGuard);
+    if (resolvedTarget === resolvedRoot) {
+        return { rootGuard, parentGuard: rootGuard };
+    }
+    assertPathWithinRoot(resolvedRoot, resolvedTarget);
+    const resolvedRootReal = rootGuard.realPath;
+    let current = resolvedRoot;
+    let targetGuard = rootGuard;
+    for (const segment of path
+        .relative(resolvedRoot, resolvedTarget)
+        .split(path.sep)
+        .filter(Boolean)) {
+        current = path.join(current, segment);
+        const parentGuard = targetGuard;
+        let created = false;
+        let identity;
+        while (true) {
+            await assertAsyncDirectoryGuard(rootGuard);
+            await assertAsyncDirectoryGuard(parentGuard);
+            try {
+                identity = await inspectPrivateDirectory(current, "directory component");
+                break;
+            }
+            catch (error) {
+                if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
+                    throw error;
+                }
+                await assertAsyncDirectoryGuard(parentGuard);
+                created = await createPrivateDirectory(current, mode);
+                // EEXIST grants no initialization authority; both outcomes need fresh type checks.
+            }
+        }
+        const currentGuard = await createAsyncDirectoryGuard(current, { bigint: true });
+        assertOwnedDirectory(identity, currentGuard.stat);
+        assertRealPathWithinRoot(resolvedRootReal, currentGuard.realPath);
+        await enforcePrivateDirectoryMode({
+            realPath: currentGuard.realPath, identity, mode, created,
+            beforeChmod: async () => {
+                await assertAsyncDirectoryGuard(parentGuard);
+                await assertAsyncDirectoryGuard(rootGuard);
+                await assertAsyncDirectoryGuard(currentGuard);
+            },
+        });
+        await assertAsyncDirectoryGuard(parentGuard);
+        await assertAsyncDirectoryGuard(rootGuard);
+        await assertAsyncDirectoryGuard(currentGuard);
+        targetGuard = currentGuard;
+    }
+    return { rootGuard, parentGuard: targetGuard };
+}
+function snapshotSecretFileWriteParams(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");
+    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 (error) {
+        if (error instanceof FsSafeError && error.code === "invalid-path")
+            throw error;
+        // Keep validation and its public error shape owned by the write path below.
+        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 = 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) {
+            throw new FsSafeError("invalid-path", `Private secret ${kind} mode must be an integer between 0o0000 and 0o7777.`);
+        }
+    }
+    const intendedParentDir = path.dirname(resolvedFile);
+    const { rootGuard, parentGuard } = await ensurePrivateDirectory(resolvedRoot, intendedParentDir, dirMode);
+    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) {
+    const { mode, rootGuard, parentGuard, fileName, finalFilePath } = await prepareSecretFileWrite(params);
+    try {
+        const stat = fs.lstatSync(finalFilePath);
+        if (createOnly) {
+            throw new FsSafeError("secret-exists", `Private secret file ${finalFilePath} already exists.`);
+        }
+        if (stat.isSymbolicLink()) {
+            throw new Error(`Private secret file ${finalFilePath} must not be a symlink.`);
+        }
+        if (!stat.isFile()) {
+            throw new Error(`Private secret file ${finalFilePath} must be a regular file.`);
+        }
+    }
+    catch (error) {
+        if (!error || typeof error !== "object" || !("code" in error) || error.code !== "ENOENT") {
+            throw error;
+        }
+    }
+    await assertAsyncDirectoryGuard(rootGuard);
+    await assertAsyncDirectoryGuard(parentGuard);
+    await runPinnedWriteHelper({
+        rootPath: parentGuard.realPath,
+        relativeParentPath: "",
+        basename: fileName,
+        mkdir: false,
+        mode,
+        verifyPosixMode: true,
+        sync: params.durable !== false,
+        strictFileSync: createOnly && params.durable === "file",
+        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 },
+        verifyPublished: async (fd, expectedIdentity, publishedParentGuard) => {
+            await assertAsyncDirectoryGuard(rootGuard);
+            await assertAsyncDirectoryGuard(parentGuard);
+            await verifyAtomicWriteResult({
+                root: {
+                    rootDir: rootGuard.dir,
+                    rootReal: rootGuard.realPath,
+                    rootWithSep: ensureTrailingSep(rootGuard.realPath),
+                    rootIdentity: { dev: rootGuard.stat.dev, ino: rootGuard.stat.ino },
+                },
+                targetPath: finalFilePath,
+                fd,
+                expectedIdentity,
+                expectedMode: mode,
+                parentGuard: publishedParentGuard,
+            });
+        },
+    });
+}
+export async function writeSecretFileAtomic(params) {
+    const ownedParams = snapshotSecretFileWriteParams(params);
+    const canonicalPath = await secretFileWriteQueueKey(ownedParams.filePath);
+    await serializePathWrite(canonicalPath, async () => {
+        await materializeSecretFileAtomic(ownedParams, false);
+    });
+}
+export async function createSecretFileAtomic(params) {
+    try {
+        const ownedParams = snapshotSecretFileWriteParams(params);
+        const canonicalPath = await secretFileWriteQueueKey(ownedParams.filePath);
+        await serializePathWrite(canonicalPath, async () => {
+            await materializeSecretFileAtomic(ownedParams, true);
+        });
+    }
+    catch (error) {
+        if ((error instanceof FsSafeError && error.code === "already-exists") ||
+            error?.code === "EEXIST") {
+            throw new FsSafeError("secret-exists", "Private secret file already exists.", { cause: error });
+        }
+        throw error;
+    }
+}

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

@@ -0,0 +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>;

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

@@ -0,0 +1,58 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+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 { 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, rejectHardlinks, previewStat, inspectInput } = prepareSecretRead(filePath, label, options);
+    let handle;
+    let raw;
+    try {
+        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 = 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);
+        inspectFileIdentitySync(() => {
+            const stat = fsSync.lstatSync(realPath, { bigint: true });
+            if (!stat.isFile())
+                throw new FsSafeError("path-mismatch", "security validation failed");
+            return stat;
+        }, openedStat);
+        inspectFileIdentitySync(() => inspectInput("secret path became a symlink"), openedStat);
+        raw = (await readFileHandleBounded(handle, maxBytes)).toString("utf8");
+    }
+    catch (error) {
+        throw secretReadError(error instanceof FsSafeError
+            ? error.code
+            : secretPathErrorCode(error) === "not-found" ? "not-found" : "read-failed", "read", label, resolvedPath, error);
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+    return trimSecretFileContent(raw, label, resolvedPath);
+}
+export async function tryReadSecretFile(filePath, label, options = {}) {
+    if (!filePath?.trim())
+        return undefined;
+    try {
+        return await readSecretFile(filePath, label, options);
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "not-found")
+            return undefined;
+        throw error;
+    }
+}

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

@@ -0,0 +1,20 @@
+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 = {
+    maxBytes?: number;
+    rejectSymlink?: boolean;
+    rejectHardlinks?: boolean;
+};
+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 prepareSecretRead(filePath: string, label: string, options: SecretFileReadOptions): {
+    resolvedPath: string;
+    maxBytes: number;
+    rejectSymlink: boolean;
+    rejectHardlinks: boolean;
+    previewStat: BigIntStats;
+    inspectInput: (symlinkMessage: string) => BigIntStats;
+};

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

@@ -0,0 +1,68 @@
+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;
+    return code === "ENOENT" || code === "ENOTDIR" ? "not-found" : "invalid-path";
+}
+export function secretReadError(code, action, label, resolvedPath, error) {
+    const cause = error instanceof Error ? error : new Error(String(error));
+    return new FsSafeError(code, `Failed to ${action} ${label} file at ${resolvedPath}: ${String(cause)}`, { cause });
+}
+export function assertSecretFilePreview(stat, label, resolvedPath, maxBytes, rejectHardlinks) {
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", `${label} file at ${resolvedPath} must be a regular file.`, { cause: undefined });
+    }
+    if (rejectHardlinks && stat.nlink > 1n) {
+        throw new FsSafeError("hardlink", `${label} file at ${resolvedPath} must not be hardlinked.`, { cause: undefined });
+    }
+    if (stat.size > maxBytes) {
+        throw new FsSafeError("too-large", `${label} file at ${resolvedPath} exceeds ${maxBytes} bytes.`, { cause: undefined });
+    }
+}
+export function trimSecretFileContent(raw, label, resolvedPath) {
+    const secret = raw.trim();
+    if (!secret) {
+        throw new FsSafeError("invalid-path", `${label} file at ${resolvedPath} is empty.`, { cause: undefined });
+    }
+    return secret;
+}
+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,
+    });
+    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

@@ -0,0 +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";

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

@@ -0,0 +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 } from "./secret-read-policy.js";
+export { readSecretFile, tryReadSecretFile } from "./secret-read-async.js";

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 {};