@openclaw/openshell-sandbox 2026.9.2 → 2026.9.3

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

@@ -0,0 +1,61 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { isNotFoundPathError, isPathInside } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+// The caller has already resolved and guarded this write target.
+export async function inheritWriteTargetMode(params) {
+    try {
+        const existing = await inspectFileIdentity(() => fsSync.lstatSync(params.targetPath, { bigint: true }));
+        if (existing.isSymbolicLink())
+            throw new FsSafeError("path-alias", "path alias escape blocked");
+        if (!existing.isFile())
+            throw new FsSafeError("not-file", "not a file");
+        if (existing.nlink > 1n)
+            throw hardlinkedPathNotAllowedError();
+        if (!isPathInside(params.rootWithSep, params.targetPath))
+            throw outsideWorkspaceError();
+        // Preserve read-open admission of the pre-existing destination. access(2)
+        // is not equivalent: it ignores ACLs on Windows and capabilities on Linux.
+        const handle = await fs.open(params.targetPath, resolveReadOpenFlags());
+        try {
+            // Bind admission to the inode whose metadata is inherited.
+            if (!sameFileIdentity(fsSync.fstatSync(handle.fd, { bigint: true }), existing)) {
+                throw new FsSafeError("path-mismatch", "write target changed during mode inheritance");
+            }
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+        try {
+            // A parent can change after guarded resolution. Do not inherit metadata
+            // from an outside inode, even if the parent is restored before publication.
+            const realPath = fsSync.realpathSync.native(params.targetPath);
+            if (!isPathInside(params.rootWithSep, realPath))
+                throw outsideWorkspaceError();
+            await inspectFileIdentity(async () => {
+                const current = fsSync.statSync(realPath, { bigint: true });
+                if (!current.isFile())
+                    throw new FsSafeError("not-file", "not a file");
+                if (current.nlink > 1n)
+                    throw hardlinkedPathNotAllowedError();
+                return current;
+            }, existing);
+        }
+        catch (error) {
+            if (isNotFoundPathError(error)) {
+                throw new FsSafeError("path-mismatch", "write target changed during mode inheritance", { cause: error });
+            }
+            throw error;
+        }
+        return params.requestedMode ?? Number(existing.mode & 511n);
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
+        return params.requestedMode ?? 0o600;
+    }
+}

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

@@ -0,0 +1,12 @@
+import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import type { PublishedWriteIdentity } from "./pinned-write.js";
+import { type RootContext } from "./root-context.js";
+export declare function verifyAtomicWriteResult(params: {
+    root: RootContext;
+    targetPath: string;
+    fd: number;
+    expectedIdentity: PublishedWriteIdentity;
+    expectedMode?: number;
+    parentGuard: AnyAsyncDirectoryGuard;
+}): Promise<void>;
+//# sourceMappingURL=root-write-verification.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"root-write-verification.d.ts","sourceRoot":"","sources":["../src/root-write-verification.ts"],"names":[],"mappings":"AAEA,OAAO,EAA6B,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAK9F,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAEhE,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhF,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,gBAAgB,EAAE,sBAAsB,CAAC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,sBAAsB,CAAC;CACrC,GAAG,OAAO,CAAC,IAAI,CAAC,CAqFhB"}

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

@@ -0,0 +1,97 @@
+import fsSync, {} from "node:fs";
+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 { resolveReadOpenFlags } from "./read-open-flags.js";
+import { assertRootIdentityCurrent } from "./root-context.js";
+import { fileNotFoundError, hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+export async function verifyAtomicWriteResult(params) {
+    let needsPathOpen = false;
+    const assertFile = (stat) => {
+        if (stat.isSymbolicLink()) {
+            throw new FsSafeError("symlink", "symlink not allowed");
+        }
+        if (!stat.isFile()) {
+            throw new FsSafeError("not-file", "not a file");
+        }
+        if (!sameFileIdentity(stat, params.expectedIdentity)) {
+            throw new FsSafeError("path-mismatch", "path changed during write");
+        }
+        if (stat.nlink > 1) {
+            throw hardlinkedPathNotAllowedError();
+        }
+    };
+    const assertPath = (stat) => {
+        assertFile(stat);
+        needsPathOpen ||= process.platform === "win32" && (stat.dev === 0n || stat.ino === 0n);
+    };
+    const assertDescriptor = (fd = params.fd) => {
+        const stat = fsSync.fstatSync(fd, { bigint: true });
+        // Only Windows pathname stats may have unknown identity; fd stats must match exactly.
+        if (params.expectedIdentity.dev !== stat.dev || params.expectedIdentity.ino !== stat.ino) {
+            throw new FsSafeError("path-mismatch", "descriptor changed during write");
+        }
+        assertFile(stat);
+        if (process.platform !== "win32" && params.expectedMode !== undefined) {
+            const actualMode = Number(stat.mode & 4095n);
+            if (actualMode !== params.expectedMode) {
+                throw new Error(`Private secret file ${params.targetPath} has insecure permissions ${actualMode.toString(8)}.`);
+            }
+        }
+        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);
+                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)) {
+                    throw outsideWorkspaceError();
+                }
+                await assertAsyncDirectoryGuard(params.parentGuard);
+                await assertRootIdentityCurrent(params.root);
+                assertPath(fsSync.lstatSync(params.targetPath, { bigint: true }));
+                assertDescriptor(opened.fd);
+            }
+            finally {
+                await opened.close().catch(() => undefined);
+            }
+        }
+    }
+    catch (error) {
+        if (isNotFoundPathError(error))
+            throw fileNotFoundError();
+        throw error;
+    }
+}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"root.d.ts","sourceRoot":"","sources":["../src/root.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,kCAAkC,EAClC,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EACV,iBAAiB,EACjB,qBAAqB,EACrB,8BAA8B,EAC9B,aAAa,EACb,mBAAmB,EACnB,yBAAyB,EACzB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,GACtB,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1 @@
+export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, } from "./root-impl.js";

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 sanitizeSafePathSegment(value: string, fallback: string, options?: SafePathSegmentOptions): string;
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-path-segment.d.ts","sourceRoot":"","sources":["../src/safe-path-segment.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,sBAAsB,GAAG;IACnC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtF;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUrD;AAED,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAaT;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAUR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAWR;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,sBAA2B,GACnC,MAAM,CAeR"}

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

@@ -0,0 +1,75 @@
+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]:(?![\\/])/;
+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)) {
+        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") &&
+        (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 sanitizeSafePathSegment(value, fallback, options = {}) {
+    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" });
+}
+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,25 @@
+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;
+};
+export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParams, "content">): 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: SecretFileWriteParams): Promise<void>;
+export {};
+//# sourceMappingURL=secret-file.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"secret-file.d.ts","sourceRoot":"","sources":["../src/secret-file.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAK/C,OAAO,EAAkF,KAAK,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAUhJ,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAIjC,eAAO,MAAM,uBAAuB,MAAQ,CAAC;AAC7C,eAAO,MAAM,wBAAwB,MAAQ,CAAC;AAE9C,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,CAkER;AAED,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,MAAM,GAAG,SAAS,CAUpB;AA8JD,KAAK,qBAAqB,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAYF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,SAAS,CAAC,GAC7C,OAAO,CAAC;IACT,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC5C,WAAW,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC,CAuBD;AAuDD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAezF"}

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

@@ -0,0 +1,329 @@
+import fs, {} from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+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 { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+import { serializePathWrite } from "./write-queue.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 opened = openPinnedFileSync({
+        filePath: resolvedPath,
+        rejectPathSymlink: options.rejectSymlink,
+        rejectHardlinks: options.rejectHardlinks !== false,
+    });
+    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);
+        inspectFileIdentitySync(() => inspectInput("secret path became a symlink"), openedIdentity);
+        raw = readFileDescriptorBoundedSync(opened.fd, maxBytes).toString("utf8");
+    }
+    catch (error) {
+        throw secretReadError(error instanceof FsSafeError ? error.code : "read-failed", "read", label, resolvedPath, error);
+    }
+    finally {
+        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 = path.resolve(rootDir);
+    const resolvedTarget = path.resolve(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(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 };
+}
+async function secretFileWriteQueueKey(filePath) {
+    try {
+        return await canonicalPathFromExistingAncestor(filePath);
+    }
+    catch {
+        // Keep validation and its public error shape owned by the write path below.
+        return path.resolve(filePath);
+    }
+}
+// Internal preparation for private writers and their pre-write locks; not lasting authorization.
+export async function prepareSecretFileWrite(params) {
+    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);
+    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);
+    const fileName = path.basename(resolvedFile);
+    const finalFilePath = path.join(parentGuard.realPath, fileName);
+    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,
+        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 canonicalPath = await secretFileWriteQueueKey(params.filePath);
+    await serializePathWrite(canonicalPath, async () => {
+        await materializeSecretFileAtomic(params, false);
+    });
+}
+export async function createSecretFileAtomic(params) {
+    try {
+        const canonicalPath = await secretFileWriteQueueKey(params.filePath);
+        await serializePathWrite(canonicalPath, async () => {
+            await materializeSecretFileAtomic(params, 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,4 @@
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-read-async.d.ts","sourceRoot":"","sources":["../src/secret-read-async.ts"],"names":[],"mappings":"AAOA,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,yBAAyB,CAAC;AAEjC,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,CAAC,CA0DjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B"}