@openclaw/fs-safe 0.2.0 → 0.2.2

package/dist/private-file-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"private-file-store.d.ts","sourceRoot":"","sources":["../src/private-file-store.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxF,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAChG,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzG,CAAC;AAgBF,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhB;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBzB;AAoBD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,GAAG,IAAI,CAiBhB;AAED,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAGpB;AAED,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,CAAC,GAAG,IAAI,CAGX;AAoCD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;CAC9B,GAAG,IAAI,CA4CP;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,IAAI,CAOP;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAiClE"}
+{"version":3,"file":"private-file-store.d.ts","sourceRoot":"","sources":["../src/private-file-store.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAM5D,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CAAC,GAAG;IACrG,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxF,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IAChG,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/E,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC3G,CAAC;AAgBF,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAEhB;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBzB;AAoBD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,MAAM,GAAG,IAAI,CAiBhB;AAED,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAGpB;AAED,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,CAAC,GAAG,IAAI,CAGX;AAoCD,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;CAC9B,GAAG,IAAI,CA4CP;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhB;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,IAAI,CAOP;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CA2CtF"}

package/dist/private-file-store.js

@@ -2,10 +2,11 @@ import { randomUUID } from "node:crypto";
 import path from "node:path";
 import fs from "node:fs";
 import { FsSafeError } from "./errors.js";
+import { fileStore } from "./file-store.js";
 import { isPathInside } from "./path.js";
 import { readRegularFileSync } from "./regular-file.js";
 import { root } from "./root.js";
-import { writePrivateSecretFileAtomic } from "./secret-file.js";
+import { writeSecretFileAtomic } from "./secret-file.js";
 function resolvePrivateStorePath(rootDir, relativePath) {
     const root = path.resolve(rootDir);
     const raw = relativePath.trim();
@@ -20,7 +21,7 @@ function resolvePrivateStorePath(rootDir, relativePath) {
     return resolved;
 }
 export async function writePrivateTextAtomic(params) {
-    await writePrivateSecretFileAtomic(params);
+    await writeSecretFileAtomic(params);
 }
 export async function readPrivateText(params) {
     const rootDir = path.resolve(params.rootDir);
@@ -172,7 +173,7 @@ export function writePrivateTextAtomicSync(params) {
 }
 export async function writePrivateJsonAtomic(params) {
     const json = JSON.stringify(params.value, null, 2);
-    await writePrivateSecretFileAtomic({
+    await writeSecretFileAtomic({
         rootDir: params.rootDir,
         filePath: params.filePath,
         content: params.trailingNewline && !json.endsWith("\n") ? `${json}\n` : json,
@@ -186,35 +187,47 @@ export function writePrivateJsonAtomicSync(params) {
         content: params.trailingNewline && !json.endsWith("\n") ? `${json}\n` : json,
     });
 }
-export function privateFileStore(rootDir) {
-    const root = path.resolve(rootDir);
+export function privateStateStore(options) {
+    const rootDir = path.resolve(options.rootDir);
+    const store = fileStore({ rootDir, private: true });
     return {
-        rootDir: root,
-        path: (relativePath) => resolvePrivateStorePath(root, relativePath),
-        readText: async (relativePath, options) => await readPrivateText({
-            rootDir: root,
-            filePath: resolvePrivateStorePath(root, relativePath),
-            maxBytes: options?.maxBytes,
-        }),
-        readJson: async (relativePath, options) => await readPrivateJson({
-            rootDir: root,
-            filePath: resolvePrivateStorePath(root, relativePath),
-            maxBytes: options?.maxBytes,
-        }),
+        ...store,
+        rootDir,
+        path: (relativePath) => resolvePrivateStorePath(rootDir, relativePath),
+        readText: async (relativePath, options) => {
+            const safePath = resolvePrivateStorePath(rootDir, relativePath);
+            return await readPrivateText({
+                rootDir,
+                filePath: safePath,
+                maxBytes: options?.maxBytes,
+            });
+        },
+        readJson: async (relativePath, options) => {
+            const safePath = resolvePrivateStorePath(rootDir, relativePath);
+            return await readPrivateJson({
+                rootDir,
+                filePath: safePath,
+                maxBytes: options?.maxBytes,
+            });
+        },
         writeText: async (relativePath, content) => {
+            const safePath = resolvePrivateStorePath(rootDir, relativePath);
             await writePrivateTextAtomic({
-                rootDir: root,
-                filePath: resolvePrivateStorePath(root, relativePath),
+                rootDir,
+                filePath: safePath,
                 content,
             });
+            return safePath;
         },
         writeJson: async (relativePath, value, options) => {
+            const safePath = resolvePrivateStorePath(rootDir, relativePath);
             await writePrivateJsonAtomic({
-                rootDir: root,
-                filePath: resolvePrivateStorePath(root, relativePath),
+                rootDir,
+                filePath: safePath,
                 value,
                 trailingNewline: options?.trailingNewline,
             });
+            return safePath;
         },
     };
 }

package/dist/root-impl.js

@@ -856,8 +856,10 @@ async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode)
     catch (err) {
         throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
     }
+    // resolvePathInRoot already enforces isPathInside, so any actual escape
+    // is rejected upstream.
     const relativeResolved = path.relative(rootReal, resolved);
-    if (relativeResolved.startsWith("..") || path.isAbsolute(relativeResolved)) {
+    if (path.isAbsolute(relativeResolved)) {
         throw new FsSafeError("outside-workspace", "file is outside workspace root");
     }
     const relativePosix = relativeResolved
@@ -919,9 +921,10 @@ async function resolvePinnedOperationPathInRoot(root, params) {
     if ((relativeResolved === "" || relativeResolved === ".") && params.allowRoot === true) {
         return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix: "" };
     }
+    const firstSegment = relativeResolved.split(path.sep)[0];
     if (relativeResolved === "" ||
         relativeResolved === "." ||
-        relativeResolved.startsWith("..") ||
+        firstSegment === ".." ||
         path.isAbsolute(relativeResolved)) {
         throw new FsSafeError("outside-workspace", "file is outside workspace root");
     }

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":"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"}