@openclaw/fs-safe 0.1.0

package/dist/safe-open-sync.d.ts

@@ -0,0 +1,24 @@
+import fs from "node:fs";
+export type SafeOpenSyncFailureReason = "path" | "validation" | "io";
+export type SafeOpenSyncResult = {
+    ok: true;
+    path: string;
+    fd: number;
+    stat: fs.Stats;
+} | {
+    ok: false;
+    reason: SafeOpenSyncFailureReason;
+    error?: unknown;
+};
+export type SafeOpenSyncAllowedType = "file" | "directory";
+export type SafeOpenSyncFs = Pick<typeof fs, "constants" | "lstatSync" | "realpathSync" | "openSync" | "fstatSync" | "closeSync">;
+export declare function openVerifiedFileSync(params: {
+    filePath: string;
+    resolvedPath?: string;
+    rejectPathSymlink?: boolean;
+    rejectHardlinks?: boolean;
+    maxBytes?: number;
+    allowedType?: SafeOpenSyncAllowedType;
+    ioFs?: SafeOpenSyncFs;
+}): SafeOpenSyncResult;
+//# sourceMappingURL=safe-open-sync.d.ts.map

package/dist/safe-open-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-open-sync.d.ts","sourceRoot":"","sources":["../src/safe-open-sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAGzB,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;AAErE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,WAAW,CAAC;AAE3D,MAAM,MAAM,cAAc,GAAG,IAAI,CAC/B,OAAO,EAAE,EACT,WAAW,GAAG,WAAW,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CACpF,CAAC;AAYF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,GAAG,kBAAkB,CA2DrB"}

package/dist/safe-open-sync.js

@@ -0,0 +1,71 @@
+import fs from "node:fs";
+import { sameFileIdentity as hasSameFileIdentity } from "./file-identity.js";
+function isExpectedPathError(error) {
+    const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
+    return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
+}
+function sameFileIdentity(left, right) {
+    return hasSameFileIdentity(left, right);
+}
+export function openVerifiedFileSync(params) {
+    const ioFs = params.ioFs ?? fs;
+    const allowedType = params.allowedType ?? "file";
+    const openReadFlags = ioFs.constants.O_RDONLY |
+        (typeof ioFs.constants.O_NOFOLLOW === "number" ? ioFs.constants.O_NOFOLLOW : 0);
+    let fd = null;
+    try {
+        if (params.rejectPathSymlink) {
+            const candidateStat = ioFs.lstatSync(params.filePath);
+            if (candidateStat.isSymbolicLink()) {
+                return { ok: false, reason: "validation" };
+            }
+        }
+        const realPath = params.resolvedPath ?? ioFs.realpathSync(params.filePath);
+        const preOpenStat = ioFs.lstatSync(realPath);
+        if (!isAllowedType(preOpenStat, allowedType)) {
+            return { ok: false, reason: "validation" };
+        }
+        if (params.rejectHardlinks && preOpenStat.isFile() && preOpenStat.nlink > 1) {
+            return { ok: false, reason: "validation" };
+        }
+        if (params.maxBytes !== undefined &&
+            preOpenStat.isFile() &&
+            preOpenStat.size > params.maxBytes) {
+            return { ok: false, reason: "validation" };
+        }
+        fd = ioFs.openSync(realPath, openReadFlags);
+        const openedStat = ioFs.fstatSync(fd);
+        if (!isAllowedType(openedStat, allowedType)) {
+            return { ok: false, reason: "validation" };
+        }
+        if (params.rejectHardlinks && openedStat.isFile() && openedStat.nlink > 1) {
+            return { ok: false, reason: "validation" };
+        }
+        if (params.maxBytes !== undefined && openedStat.isFile() && openedStat.size > params.maxBytes) {
+            return { ok: false, reason: "validation" };
+        }
+        if (!sameFileIdentity(preOpenStat, openedStat)) {
+            return { ok: false, reason: "validation" };
+        }
+        const opened = { ok: true, path: realPath, fd, stat: openedStat };
+        fd = null;
+        return opened;
+    }
+    catch (error) {
+        if (isExpectedPathError(error)) {
+            return { ok: false, reason: "path", error };
+        }
+        return { ok: false, reason: "io", error };
+    }
+    finally {
+        if (fd !== null) {
+            ioFs.closeSync(fd);
+        }
+    }
+}
+function isAllowedType(stat, allowedType) {
+    if (allowedType === "directory") {
+        return stat.isDirectory();
+    }
+    return stat.isFile();
+}

package/dist/safe-root.d.ts

@@ -0,0 +1,123 @@
+import type { Stats } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import type { SafeDirEntry, SafePathStat } from "./types.js";
+export type SafeOpenResult = {
+    handle: FileHandle;
+    realPath: string;
+    stat: Stats;
+};
+export type SafeLocalReadResult = {
+    buffer: Buffer;
+    realPath: string;
+    stat: Stats;
+};
+export type SafeRootContext = {
+    rootDir: string;
+    rootReal: string;
+    rootWithSep: string;
+};
+export type SafeRootOptions = {
+    rootDir: string;
+    defaults?: SafeRootDefaults;
+};
+export type SafeRootDefaults = {
+    append?: SafeRootAppendOptions;
+    copy?: SafeRootCopyOptions;
+    /** openFile merges read defaults first, then open defaults, then call options. */
+    open?: SafeRootOpenOptions;
+    openWritable?: SafeRootOpenWritableOptions;
+    read?: SafeRootReadOptions;
+    write?: SafeRootWriteOptions;
+};
+export type SafeRootSymlinkPolicy = "reject" | "follow-within-root";
+export type SafeRootReadOptions = {
+    rejectHardlinks?: boolean;
+    nonBlockingRead?: boolean;
+    symlinkPolicy?: SafeRootSymlinkPolicy;
+    maxBytes?: number;
+};
+export type SafeRootOpenOptions = Omit<SafeRootReadOptions, "maxBytes">;
+export type SafeRootWriteOptions = {
+    encoding?: BufferEncoding;
+    mkdir?: boolean;
+};
+export type SafeRootOpenWritableOptions = {
+    mkdir?: boolean;
+    mode?: number;
+    truncateExisting?: boolean;
+    append?: boolean;
+};
+export type SafeRootCopyOptions = {
+    maxBytes?: number;
+    mkdir?: boolean;
+    rejectSourceHardlinks?: boolean;
+};
+export type SafeRootWriteJsonOptions = SafeRootWriteOptions & {
+    replacer?: Parameters<typeof JSON.stringify>[1];
+    space?: Parameters<typeof JSON.stringify>[2];
+    trailingNewline?: boolean;
+};
+export type SafeRootCreateOptions = SafeRootWriteOptions;
+export type SafeRootCreateJsonOptions = SafeRootWriteJsonOptions;
+export type SafeRootAppendOptions = {
+    encoding?: BufferEncoding;
+    mkdir?: boolean;
+    prependNewlineIfNeeded?: boolean;
+};
+export declare class SafeRoot {
+    readonly rootDir: string;
+    readonly rootReal: string;
+    readonly rootWithSep: string;
+    readonly defaults: SafeRootDefaults;
+    constructor(context: SafeRootContext, defaults?: SafeRootDefaults);
+    private get context();
+    resolve(relativePath: string): Promise<string>;
+    openFile(relativePath: string, options?: SafeRootOpenOptions): Promise<SafeOpenResult>;
+    readFile(relativePath: string, options?: SafeRootReadOptions): Promise<SafeLocalReadResult>;
+    readFileBytes(relativePath: string, options?: SafeRootReadOptions): Promise<Buffer>;
+    readText(relativePath: string, options?: SafeRootReadOptions & {
+        encoding?: BufferEncoding;
+    }): Promise<string>;
+    readJson<T = unknown>(relativePath: string, options?: SafeRootReadOptions & {
+        encoding?: BufferEncoding;
+    }): Promise<T>;
+    readPath(filePath: string, options?: Pick<SafeRootReadOptions, "rejectHardlinks" | "maxBytes">): Promise<SafeLocalReadResult>;
+    reader(options?: Pick<SafeRootReadOptions, "rejectHardlinks" | "maxBytes">): (filePath: string) => Promise<Buffer>;
+    openWritable(relativePath: string, options?: SafeRootOpenWritableOptions): Promise<SafeWritableOpenResult>;
+    append(relativePath: string, data: string | Buffer, options?: SafeRootAppendOptions): Promise<void>;
+    removeFile(relativePath: string): Promise<void>;
+    mkdirp(relativePath: string, options?: {
+        allowRoot?: boolean;
+    }): Promise<void>;
+    writeFile(relativePath: string, data: string | Buffer, options?: SafeRootWriteOptions): Promise<void>;
+    createFile(relativePath: string, data: string | Buffer, options?: SafeRootCreateOptions): Promise<boolean>;
+    writeJson(relativePath: string, data: unknown, options?: SafeRootWriteJsonOptions): Promise<void>;
+    createJson(relativePath: string, data: unknown, options?: SafeRootCreateJsonOptions): Promise<boolean>;
+    copyFileFrom(sourcePath: string, relativePath: string, options?: SafeRootCopyOptions): Promise<void>;
+    statPath(relativePath: string): Promise<SafePathStat>;
+    listDir(relativePath: string, options?: {
+        withFileTypes?: false;
+    }): Promise<string[]>;
+    listDir(relativePath: string, options: {
+        withFileTypes: true;
+    }): Promise<SafeDirEntry[]>;
+    move(from: string, to: string, options?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+}
+export declare function safeRoot(rootDir: string, defaults?: SafeRootDefaults): Promise<SafeRoot>;
+export declare function readLocalFileSafely(params: {
+    filePath: string;
+    maxBytes?: number;
+}): Promise<SafeLocalReadResult>;
+export declare function openLocalFileSafely(params: {
+    filePath: string;
+}): Promise<SafeOpenResult>;
+export type SafeWritableOpenResult = {
+    handle: FileHandle;
+    createdForWrite: boolean;
+    realPath: string;
+    stat: Stats;
+};
+export declare function resolveOpenedFileRealPathForHandle(handle: FileHandle, ioPath: string): Promise<string>;
+//# sourceMappingURL=safe-root.d.ts.map

package/dist/safe-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-root.d.ts","sourceRoot":"","sources":["../src/safe-root.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAErC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAoBnD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7D,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,gBAAgB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,qBAAqB,CAAC;IAC/B,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,kFAAkF;IAClF,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,YAAY,CAAC,EAAE,2BAA2B,CAAC;IAC3C,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,KAAK,CAAC,EAAE,oBAAoB,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,oBAAoB,CAAC;AAEpE,MAAM,MAAM,mBAAmB,GAAG;IAChC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,CAAC;AAExE,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,oBAAoB,GAAG;IAC5D,QAAQ,CAAC,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,KAAK,CAAC,EAAE,UAAU,CAAC,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,oBAAoB,CAAC;AACzD,MAAM,MAAM,yBAAyB,GAAG,wBAAwB,CAAC;AAEjE,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC,CAAC;AA4LF,qBAAa,QAAQ;IACnB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;gBAExB,OAAO,EAAE,eAAe,EAAE,QAAQ,GAAE,gBAAqB;IAOrE,OAAO,KAAK,OAAO,GAMlB;IAEK,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9C,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,cAAc,CAAC;IAS1F,QAAQ,CACZ,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,mBAAmB,CAAC;IAQzB,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,MAAM,CAAC;IAIvF,QAAQ,CACZ,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,mBAAmB,GAAG;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAO,GAChE,OAAO,CAAC,MAAM,CAAC;IAKZ,QAAQ,CAAC,CAAC,GAAG,OAAO,EACxB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,mBAAmB,GAAG;QAAE,QAAQ,CAAC,EAAE,cAAc,CAAA;KAAO,GAChE,OAAO,CAAC,CAAC,CAAC;IAIP,QAAQ,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,iBAAiB,GAAG,UAAU,CAAM,GACtE,OAAO,CAAC,mBAAmB,CAAC;IAI/B,MAAM,CAAC,OAAO,GAAE,IAAI,CAAC,mBAAmB,EAAE,iBAAiB,GAAG,UAAU,CAAM,IAC9D,UAAU,MAAM,KAAG,OAAO,CAAC,MAAM,CAAC;IAK5C,YAAY,CAChB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,2BAAgC,GACxC,OAAO,CAAC,sBAAsB,CAAC;IAQ5B,MAAM,CACV,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC;IASV,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,MAAM,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlF,SAAS,CACb,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC;IASV,UAAU,CACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,OAAO,CAAC;IAUb,SAAS,CACb,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,IAAI,CAAC;IAMV,UAAU,CACd,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,yBAA8B,GACtC,OAAO,CAAC,OAAO,CAAC;IAMb,YAAY,CAChB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAAC,IAAI,CAAC;IASV,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAIrD,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IACrF,OAAO,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,aAAa,EAAE,IAAI,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAUxF,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAO3F;AAED,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,gBAAqB,GAC9B,OAAO,CAAC,QAAQ,CAAC,CAEnB;AA6ED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAO/B;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,CAAC,CAE/F;AAoBD,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,UAAU,CAAC;IACnB,eAAe,EAAE,OAAO,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAiDF,wBAAsB,kCAAkC,CACtD,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAoCjB"}