@openclaw/fs-safe 0.2.1 → 0.2.2

package/dist/json-file.js

@@ -0,0 +1,123 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const JSON_FILE_MODE = 0o600;
+const JSON_DIR_MODE = 0o700;
+function trySetSecureMode(pathname) {
+    try {
+        fs.chmodSync(pathname, JSON_FILE_MODE);
+    }
+    catch {
+        // best-effort on platforms without chmod support
+    }
+}
+function trySyncDirectory(pathname) {
+    let fd;
+    try {
+        fd = fs.openSync(path.dirname(pathname), "r");
+        fs.fsyncSync(fd);
+    }
+    catch {
+        // best-effort; some platforms/filesystems do not support syncing directories.
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }
+    }
+}
+function readSymlinkTargetPath(linkPath) {
+    const target = fs.readlinkSync(linkPath);
+    return path.resolve(path.dirname(linkPath), target);
+}
+function resolveJsonWriteTarget(pathname) {
+    let currentPath = pathname;
+    const visited = new Set();
+    let followsSymlink = false;
+    for (;;) {
+        let stat;
+        try {
+            stat = fs.lstatSync(currentPath);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+            return { targetPath: currentPath, followsSymlink };
+        }
+        if (!stat.isSymbolicLink()) {
+            return { targetPath: currentPath, followsSymlink };
+        }
+        if (visited.has(currentPath)) {
+            const err = new Error(`Too many symlink levels while resolving ${pathname}`);
+            err.code = "ELOOP";
+            throw err;
+        }
+        visited.add(currentPath);
+        followsSymlink = true;
+        currentPath = readSymlinkTargetPath(currentPath);
+    }
+}
+function renameJsonFileWithFallback(tmpPath, pathname) {
+    try {
+        fs.renameSync(tmpPath, pathname);
+        return;
+    }
+    catch (error) {
+        const code = error.code;
+        // Windows does not reliably support rename-based overwrite for existing files.
+        if (code === "EPERM" || code === "EEXIST") {
+            fs.copyFileSync(tmpPath, pathname);
+            fs.rmSync(tmpPath, { force: true });
+            return;
+        }
+        throw error;
+    }
+}
+function writeTempJsonFile(pathname, payload) {
+    const fd = fs.openSync(pathname, "w", JSON_FILE_MODE);
+    try {
+        fs.writeFileSync(fd, payload, "utf8");
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function loadJsonFile(pathname) {
+    try {
+        const raw = fs.readFileSync(pathname, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveJsonFile(pathname, data) {
+    const { targetPath, followsSymlink } = resolveJsonWriteTarget(pathname);
+    const tmpPath = `${targetPath}.${randomUUID()}.tmp`;
+    const payload = `${JSON.stringify(data, null, 2)}\n`;
+    if (!followsSymlink) {
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true, mode: JSON_DIR_MODE });
+    }
+    try {
+        writeTempJsonFile(tmpPath, payload);
+        trySetSecureMode(tmpPath);
+        renameJsonFileWithFallback(tmpPath, targetPath);
+        trySetSecureMode(targetPath);
+        trySyncDirectory(targetPath);
+    }
+    finally {
+        try {
+            fs.rmSync(tmpPath, { force: true });
+        }
+        catch {
+            // best-effort cleanup when rename does not happen
+        }
+    }
+}

package/dist/json-files.d.ts

@@ -0,0 +1,20 @@
+export declare class JsonFileReadError extends Error {
+    readonly filePath: string;
+    readonly reason: "read" | "parse";
+    constructor(filePath: string, reason: "read" | "parse", cause: unknown);
+}
+export declare function readJsonFile<T>(filePath: string): Promise<T | null>;
+export declare function readDurableJsonFile<T>(filePath: string): Promise<T | null>;
+export declare function readJsonFileSync(filePath: string): unknown;
+export declare function writeJsonAtomic(filePath: string, value: unknown, options?: {
+    mode?: number;
+    trailingNewline?: boolean;
+    ensureDirMode?: number;
+}): Promise<void>;
+export declare function writeTextAtomic(filePath: string, content: string, options?: {
+    mode?: number;
+    ensureDirMode?: number;
+    appendTrailingNewline?: boolean;
+}): Promise<void>;
+export declare function createAsyncLock(): <T>(fn: () => Promise<T>) => Promise<T>;
+//# sourceMappingURL=json-files.d.ts.map

package/dist/json-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-files.d.ts","sourceRoot":"","sources":["../src/json-files.ts"],"names":[],"mappings":"AASA,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;gBAEtB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO;CAMvE;AA6BD,wBAAsB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAOzE;AAED,wBAAsB,mBAAmB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAehF;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAO1D;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,iBAQ/E;AAED,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAAE,iBA4CrF;AAED,wBAAgB,eAAe,KAEE,CAAC,EAAE,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CAapE"}

package/dist/json-files.js

@@ -0,0 +1,153 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+function getErrorCode(err) {
+    return err instanceof Error ? err.code : undefined;
+}
+export class JsonFileReadError extends Error {
+    filePath;
+    reason;
+    constructor(filePath, reason, cause) {
+        super(`Failed to ${reason} JSON file: ${filePath}`, { cause });
+        this.name = "JsonFileReadError";
+        this.filePath = filePath;
+        this.reason = reason;
+    }
+}
+async function replaceFileWithWindowsFallback(tempPath, filePath, mode) {
+    try {
+        await fs.rename(tempPath, filePath);
+        return;
+    }
+    catch (err) {
+        const code = getErrorCode(err);
+        if (process.platform !== "win32" || (code !== "EPERM" && code !== "EEXIST")) {
+            throw err;
+        }
+    }
+    const existing = await fs.lstat(filePath).catch(() => null);
+    if (existing?.isSymbolicLink()) {
+        await fs.rm(filePath, { force: true });
+        await fs.rename(tempPath, filePath);
+        return;
+    }
+    await fs.copyFile(tempPath, filePath);
+    try {
+        await fs.chmod(filePath, mode);
+    }
+    catch {
+        // best-effort; ignore on platforms without chmod
+    }
+    await fs.rm(tempPath, { force: true }).catch(() => undefined);
+}
+export async function readJsonFile(filePath) {
+    try {
+        const raw = await fs.readFile(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function readDurableJsonFile(filePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (getErrorCode(err) === "ENOENT") {
+            return null;
+        }
+        throw new JsonFileReadError(filePath, "read", err);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JsonFileReadError(filePath, "parse", err);
+    }
+}
+export function readJsonFileSync(filePath) {
+    try {
+        const raw = readFileSync(filePath, "utf8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeJsonAtomic(filePath, value, options) {
+    const text = JSON.stringify(value, null, 2);
+    await writeTextAtomic(filePath, text, {
+        mode: options?.mode,
+        ensureDirMode: options?.ensureDirMode,
+        appendTrailingNewline: options?.trailingNewline,
+    });
+}
+export async function writeTextAtomic(filePath, content, options) {
+    const mode = options?.mode ?? 0o600;
+    const payload = options?.appendTrailingNewline && !content.endsWith("\n") ? `${content}\n` : content;
+    const mkdirOptions = { recursive: true };
+    if (typeof options?.ensureDirMode === "number") {
+        mkdirOptions.mode = options.ensureDirMode;
+    }
+    await fs.mkdir(path.dirname(filePath), mkdirOptions);
+    const parentDir = path.dirname(filePath);
+    const tmp = `${filePath}.${randomUUID()}.tmp`;
+    try {
+        const tmpHandle = await fs.open(tmp, "w", mode);
+        try {
+            await tmpHandle.writeFile(payload, { encoding: "utf8" });
+            await tmpHandle.sync();
+        }
+        finally {
+            await tmpHandle.close().catch(() => undefined);
+        }
+        try {
+            await fs.chmod(tmp, mode);
+        }
+        catch {
+            // best-effort; ignore on platforms without chmod
+        }
+        await replaceFileWithWindowsFallback(tmp, filePath, mode);
+        try {
+            const dirHandle = await fs.open(parentDir, "r");
+            try {
+                await dirHandle.sync();
+            }
+            finally {
+                await dirHandle.close().catch(() => undefined);
+            }
+        }
+        catch {
+            // best-effort; some platforms/filesystems do not support syncing directories.
+        }
+        try {
+            await fs.chmod(filePath, mode);
+        }
+        catch {
+            // best-effort; ignore on platforms without chmod
+        }
+    }
+    finally {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+    }
+}
+export function createAsyncLock() {
+    let lock = Promise.resolve();
+    return async function withLock(fn) {
+        const prev = lock;
+        let release;
+        lock = new Promise((resolve) => {
+            release = resolve;
+        });
+        await prev;
+        try {
+            return await fn();
+        }
+        finally {
+            release?.();
+        }
+    };
+}

package/dist/path-alias-guards.d.ts

@@ -0,0 +1,19 @@
+import { type RootPathAliasPolicy } from "./root-path.js";
+export type PathAliasPolicy = RootPathAliasPolicy;
+export declare const PATH_ALIAS_POLICIES: {
+    readonly strict: Readonly<{
+        allowFinalSymlinkForUnlink: false;
+        allowFinalHardlinkForUnlink: false;
+    }>;
+    readonly unlinkTarget: Readonly<{
+        allowFinalSymlinkForUnlink: true;
+        allowFinalHardlinkForUnlink: true;
+    }>;
+};
+export declare function assertNoPathAliasEscape(params: {
+    absolutePath: string;
+    rootPath: string;
+    boundaryLabel: string;
+    policy?: PathAliasPolicy;
+}): Promise<void>;
+//# sourceMappingURL=path-alias-guards.d.ts.map

package/dist/path-alias-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-alias-guards.d.ts","sourceRoot":"","sources":["../src/path-alias-guards.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,gBAAgB,CAAC;AAGxB,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,eAAO,MAAM,mBAAmB;;;;;;;;;CAA2B,CAAC;AAE5D,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBhB"}

package/dist/path-alias-guards.js

@@ -0,0 +1,21 @@
+import { ROOT_PATH_ALIAS_POLICIES, resolveRootPath, } from "./root-path.js";
+import { assertNoHardlinkedFinalPath } from "./hardlink-guards.js";
+export const PATH_ALIAS_POLICIES = ROOT_PATH_ALIAS_POLICIES;
+export async function assertNoPathAliasEscape(params) {
+    const resolved = await resolveRootPath({
+        absolutePath: params.absolutePath,
+        rootPath: params.rootPath,
+        boundaryLabel: params.boundaryLabel,
+        policy: params.policy,
+    });
+    const allowFinalSymlink = params.policy?.allowFinalSymlinkForUnlink === true;
+    if (allowFinalSymlink && resolved.kind === "symlink") {
+        return;
+    }
+    await assertNoHardlinkedFinalPath({
+        filePath: resolved.absolutePath,
+        root: resolved.rootPath,
+        boundaryLabel: params.boundaryLabel,
+        allowFinalHardlinkForUnlink: params.policy?.allowFinalHardlinkForUnlink,
+    });
+}

package/dist/path-guards.d.ts

@@ -0,0 +1,7 @@
+export declare function normalizeWindowsPathForComparison(input: string): string;
+export declare function isNodeError(value: unknown): value is NodeJS.ErrnoException;
+export declare function hasNodeErrorCode(value: unknown, code: string): boolean;
+export declare function isNotFoundPathError(value: unknown): boolean;
+export declare function isSymlinkOpenError(value: unknown): boolean;
+export declare function isPathInside(root: string, target: string): boolean;
+//# sourceMappingURL=path-guards.d.ts.map

package/dist/path-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-guards.d.ts","sourceRoot":"","sources":["../src/path-guards.ts"],"names":[],"mappings":"AAQA,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA0BlE"}

package/dist/path-guards.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
+const NOT_FOUND_CODES = new Set(["ENOENT", "ENOTDIR"]);
+const SYMLINK_OPEN_CODES = new Set(["ELOOP", "EINVAL", "ENOTSUP"]);
+const PARENT_SEGMENT_PREFIX = /^\.\.(?:[\\/]|$)/u;
+const POSIX_SEPARATOR_CHAR_CODE = 0x2f;
+export function normalizeWindowsPathForComparison(input) {
+    let normalized = path.win32.normalize(input);
+    if (normalized.startsWith("\\\\?\\")) {
+        normalized = normalized.slice(4);
+        if (normalized.toUpperCase().startsWith("UNC\\")) {
+            normalized = `\\\\${normalized.slice(4)}`;
+        }
+    }
+    return normalizeLowercaseStringOrEmpty(normalized.replaceAll("/", "\\"));
+}
+export function isNodeError(value) {
+    return Boolean(value && typeof value === "object" && "code" in value);
+}
+export function hasNodeErrorCode(value, code) {
+    return isNodeError(value) && value.code === code;
+}
+export function isNotFoundPathError(value) {
+    return isNodeError(value) && typeof value.code === "string" && NOT_FOUND_CODES.has(value.code);
+}
+export function isSymlinkOpenError(value) {
+    return isNodeError(value) && typeof value.code === "string" && SYMLINK_OPEN_CODES.has(value.code);
+}
+export function isPathInside(root, target) {
+    if (process.platform === "win32") {
+        const rootForCompare = normalizeWindowsPathForComparison(path.win32.resolve(root));
+        const targetForCompare = normalizeWindowsPathForComparison(path.win32.resolve(target));
+        const relative = path.win32.relative(rootForCompare, targetForCompare);
+        return (relative === "" || (!PARENT_SEGMENT_PREFIX.test(relative) && !path.win32.isAbsolute(relative)));
+    }
+    if (root.length > 0 &&
+        root.charCodeAt(0) === POSIX_SEPARATOR_CHAR_CODE &&
+        target.length >= root.length &&
+        target.charCodeAt(0) === POSIX_SEPARATOR_CHAR_CODE &&
+        !target.includes("/..") &&
+        (target === root ||
+            (target.startsWith(root) && target.charCodeAt(root.length) === POSIX_SEPARATOR_CHAR_CODE))) {
+        return true;
+    }
+    const resolvedRoot = path.resolve(root);
+    const resolvedTarget = path.resolve(target);
+    const relative = path.relative(resolvedRoot, resolvedTarget);
+    return relative === "" || (!PARENT_SEGMENT_PREFIX.test(relative) && !path.isAbsolute(relative));
+}

package/dist/path-safety.d.ts

@@ -0,0 +1,12 @@
+import fs from "node:fs";
+export declare function resolveSafeBaseDir(rootDir: string): string;
+export declare function isWithinDir(rootDir: string, targetPath: string): boolean;
+export declare function isPathInside(baseDir: string, targetPath: string): boolean;
+export declare function safeRealpathSync(targetPath: string, cache?: Map<string, string>): string | null;
+export declare function isPathInsideWithRealpath(basePath: string, candidatePath: string, opts?: {
+    requireRealpath?: boolean;
+    cache?: Map<string, string>;
+}): boolean;
+export declare function safeStatSync(targetPath: string): fs.Stats | null;
+export declare function formatPosixMode(mode: number): string;
+//# sourceMappingURL=path-safety.d.ts.map

package/dist/path-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.d.ts","sourceRoot":"","sources":["../src/path-safety.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAIzB,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAEzE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChE,OAAO,CAUT;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAMhE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD"}

package/dist/path-safety.js

@@ -0,0 +1,50 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isPathInside as isRootPathInside } from "./path-guards.js";
+export function resolveSafeBaseDir(rootDir) {
+    const resolved = path.resolve(rootDir);
+    return resolved.endsWith(path.sep) ? resolved : `${resolved}${path.sep}`;
+}
+export function isWithinDir(rootDir, targetPath) {
+    return isRootPathInside(rootDir, targetPath);
+}
+export function isPathInside(baseDir, targetPath) {
+    return isRootPathInside(baseDir, targetPath);
+}
+export function safeRealpathSync(targetPath, cache) {
+    const cached = cache?.get(targetPath);
+    if (cached) {
+        return cached;
+    }
+    try {
+        const resolved = fs.realpathSync(targetPath);
+        cache?.set(targetPath, resolved);
+        cache?.set(resolved, resolved);
+        return resolved;
+    }
+    catch {
+        return null;
+    }
+}
+export function isPathInsideWithRealpath(basePath, candidatePath, opts) {
+    if (!isPathInside(basePath, candidatePath)) {
+        return false;
+    }
+    const baseReal = safeRealpathSync(basePath, opts?.cache);
+    const candidateReal = safeRealpathSync(candidatePath, opts?.cache);
+    if (!baseReal || !candidateReal) {
+        return opts?.requireRealpath === false;
+    }
+    return isPathInside(baseReal, candidateReal);
+}
+export function safeStatSync(targetPath) {
+    try {
+        return fs.statSync(targetPath);
+    }
+    catch {
+        return null;
+    }
+}
+export function formatPosixMode(mode) {
+    return (mode & 0o777).toString(8).padStart(3, "0");
+}

package/dist/pinned-python-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pinned-python-config.d.ts","sourceRoot":"","sources":["../src/pinned-python-config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAqBF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAE/E;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,CAc1D;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAOlE"}
+{"version":3,"file":"pinned-python-config.d.ts","sourceRoot":"","sources":["../src/pinned-python-config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAqBF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAE/E;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,CAc1D;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMlE"}

package/dist/pinned-python-config.js

@@ -32,8 +32,7 @@ export function getFsSafePythonConfig() {
     };
 }
 export function canFallbackFromPythonError(error) {
+    const code = error instanceof Error && "code" in error ? error.code : undefined;
     return (getFsSafePythonConfig().mode !== "require" &&
-        error instanceof Error &&
-        "code" in error &&
-        error.code === "helper-unavailable");
+        (code === "helper-unavailable" || code === "unsupported-platform"));
 }

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

@@ -1,16 +1,18 @@
-export type PrivateFileStore = {
+import { type FileStore } from "./file-store.js";
+export type PrivateStateStoreOptions = {
     rootDir: string;
-    path(relativePath: string): string;
+};
+export type PrivateStateStore = Omit<FileStore, "readText" | "readJson" | "writeText" | "writeJson"> & {
     readText(relativePath: string, options?: {
         maxBytes?: number;
     }): Promise<string | null>;
     readJson<T = unknown>(relativePath: string, options?: {
         maxBytes?: number;
     }): Promise<T | null>;
-    writeText(relativePath: string, content: string | Uint8Array): Promise<void>;
+    writeText(relativePath: string, content: string | Uint8Array): Promise<string>;
     writeJson(relativePath: string, value: unknown, options?: {
         trailingNewline?: boolean;
-    }): Promise<void>;
+    }): Promise<string>;
 };
 export declare function writePrivateTextAtomic(params: {
     rootDir: string;
@@ -54,5 +56,5 @@ export declare function writePrivateJsonAtomicSync(params: {
     value: unknown;
     trailingNewline?: boolean;
 }): void;
-export declare function privateFileStore(rootDir: string): PrivateFileStore;
+export declare function privateStateStore(options: PrivateStateStoreOptions): PrivateStateStore;
 //# sourceMappingURL=private-file-store.d.ts.map

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

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