@openclaw/fs-safe 0.1.1 → 0.2.0

package/dist/root.js

@@ -1,1332 +1 @@
-import { randomUUID } from "node:crypto";
-import { constants as fsConstants } from "node:fs";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { Transform } from "node:stream";
-import { pipeline } from "node:stream/promises";
-import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
-import { isPinnedPathHelperSpawnError, runPinnedPathHelper } from "./pinned-path.js";
-import { runPinnedCopyHelper, runPinnedWriteHelper } from "./pinned-write.js";
-import { canFallbackFromPythonError, getFsSafePythonConfig } from "./pinned-python-config.js";
-import { expandHomePrefix } from "./home-dir.js";
-import { assertNoPathAliasEscape, PATH_ALIAS_POLICIES } from "./path-policy.js";
-import { hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError, } from "./path.js";
-import { helperReaddir, helperStat, runPinnedHelper, } from "./pinned-helper.js";
-import { resolveRootPath } from "./root-path.js";
-import { getFsSafeTestHooks } from "./test-hooks.js";
-import { registerTempPathForExit } from "./temp-cleanup.js";
-import { serializePathWrite } from "./write-queue.js";
-function logWarn(message) {
-    if (process.env.FS_SAFE_DEBUG_WARNINGS === "1") {
-        console.warn(message);
-    }
-}
-const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
-const NONBLOCK_OPEN_FLAG = "O_NONBLOCK" in fsConstants ? fsConstants.O_NONBLOCK : 0;
-const OPEN_READ_FLAGS = fsConstants.O_RDONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
-const OPEN_READ_NONBLOCK_FLAGS = OPEN_READ_FLAGS | NONBLOCK_OPEN_FLAG;
-const OPEN_READ_FOLLOW_FLAGS = fsConstants.O_RDONLY;
-const OPEN_READ_FOLLOW_NONBLOCK_FLAGS = OPEN_READ_FOLLOW_FLAGS | NONBLOCK_OPEN_FLAG;
-const OPEN_WRITE_EXISTING_FLAGS = fsConstants.O_WRONLY | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
-const OPEN_WRITE_CREATE_FLAGS = fsConstants.O_WRONLY |
-    fsConstants.O_CREAT |
-    fsConstants.O_EXCL |
-    (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
-const OPEN_APPEND_EXISTING_FLAGS = fsConstants.O_RDWR | fsConstants.O_APPEND | (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
-const OPEN_APPEND_CREATE_FLAGS = fsConstants.O_RDWR |
-    fsConstants.O_APPEND |
-    fsConstants.O_CREAT |
-    fsConstants.O_EXCL |
-    (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
-export const DEFAULT_ROOT_MAX_BYTES = 16 * 1024 * 1024;
-function closeHandleForDispose(handle) {
-    return handle.close().catch(() => undefined);
-}
-function openResult(params) {
-    return {
-        handle: params.handle,
-        realPath: params.realPath,
-        stat: params.stat,
-        [Symbol.asyncDispose]: async () => {
-            await closeHandleForDispose(params.handle);
-        },
-    };
-}
-const ensureTrailingSep = (value) => (value.endsWith(path.sep) ? value : value + path.sep);
-let cachedHomePath;
-async function expandRelativePathWithHome(relativePath) {
-    const rawHome = process.env.HOME || process.env.USERPROFILE || os.homedir();
-    if (cachedHomePath?.raw !== rawHome) {
-        let realHome = rawHome;
-        try {
-            realHome = await fs.realpath(rawHome);
-        }
-        catch {
-            // If the home dir cannot be canonicalized, keep lexical expansion behavior.
-        }
-        cachedHomePath = { raw: rawHome, real: realHome };
-    }
-    return expandHomePrefix(relativePath, { home: cachedHomePath.real });
-}
-async function openVerifiedLocalFile(filePath, options) {
-    const fsSafeTestHooks = getFsSafeTestHooks();
-    // Reject directories before opening so we never surface EISDIR to callers (e.g. tool
-    // results that get sent to messaging channels). See openclaw/openclaw#31186.
-    try {
-        const preStat = await fs.lstat(filePath);
-        if (preStat.isDirectory()) {
-            throw new FsSafeError("not-file", "not a file");
-        }
-        await fsSafeTestHooks?.afterPreOpenLstat?.(filePath);
-    }
-    catch (err) {
-        if (err instanceof FsSafeError) {
-            throw err;
-        }
-        // ENOENT and other lstat errors: fall through and let fs.open handle.
-    }
-    let handle;
-    try {
-        const openFlags = options?.symlinks === "follow-within-root"
-            ? options?.nonBlockingRead
-                ? OPEN_READ_FOLLOW_NONBLOCK_FLAGS
-                : OPEN_READ_FOLLOW_FLAGS
-            : options?.nonBlockingRead
-                ? OPEN_READ_NONBLOCK_FLAGS
-                : OPEN_READ_FLAGS;
-        await fsSafeTestHooks?.beforeOpen?.(filePath, openFlags);
-        handle = await fs.open(filePath, openFlags);
-        try {
-            await fsSafeTestHooks?.afterOpen?.(filePath, handle);
-        }
-        catch (err) {
-            await handle.close().catch(() => { });
-            throw err;
-        }
-    }
-    catch (err) {
-        if (isNotFoundPathError(err)) {
-            throw new FsSafeError("not-found", "file not found");
-        }
-        if (isSymlinkOpenError(err)) {
-            throw new FsSafeError("symlink", "symlink open blocked", { cause: err });
-        }
-        // Defensive: if open still throws EISDIR (e.g. race), sanitize so it never leaks.
-        if (hasNodeErrorCode(err, "EISDIR")) {
-            throw new FsSafeError("not-file", "not a file");
-        }
-        throw err;
-    }
-    try {
-        const stat = await handle.stat();
-        if (!stat.isFile()) {
-            throw new FsSafeError("not-file", "not a file");
-        }
-        if (options?.hardlinks === "reject" && stat.nlink > 1) {
-            throw new FsSafeError("hardlink", "hardlinked path not allowed");
-        }
-        if (options?.symlinks === "follow-within-root") {
-            const pathStat = await fs.stat(filePath);
-            if (!sameFileIdentity(stat, pathStat)) {
-                throw new FsSafeError("path-mismatch", "path changed during read");
-            }
-        }
-        else {
-            const pathStat = await fs.lstat(filePath);
-            if (pathStat.isSymbolicLink()) {
-                throw new FsSafeError("symlink", "symlink not allowed");
-            }
-            if (!sameFileIdentity(stat, pathStat)) {
-                throw new FsSafeError("path-mismatch", "path changed during read");
-            }
-        }
-        const realPath = await resolveOpenedFileRealPathForHandle(handle, filePath);
-        const realStat = await fs.stat(realPath);
-        if (options?.hardlinks === "reject" && realStat.nlink > 1) {
-            throw new FsSafeError("hardlink", "hardlinked path not allowed");
-        }
-        if (!sameFileIdentity(stat, realStat)) {
-            throw new FsSafeError("path-mismatch", "path mismatch");
-        }
-        return openResult({ handle, realPath, stat });
-    }
-    catch (err) {
-        await handle.close().catch(() => { });
-        if (err instanceof FsSafeError) {
-            throw err;
-        }
-        if (isNotFoundPathError(err)) {
-            throw new FsSafeError("not-found", "file not found");
-        }
-        throw err;
-    }
-}
-async function resolveRootContext(rootDir) {
-    let rootReal;
-    try {
-        rootReal = await fs.realpath(rootDir);
-    }
-    catch (err) {
-        if (isNotFoundPathError(err)) {
-            throw new FsSafeError("not-found", "root dir not found");
-        }
-        throw err;
-    }
-    return {
-        rootDir: path.resolve(rootDir),
-        rootReal,
-        rootWithSep: ensureTrailingSep(rootReal),
-    };
-}
-async function resolvePathInRoot(root, relativePath) {
-    const expanded = await expandRelativePathWithHome(relativePath);
-    const resolved = path.resolve(root.rootWithSep, expanded);
-    if (!isPathInside(root.rootWithSep, resolved)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
-    }
-    return { rootReal: root.rootReal, rootWithSep: root.rootWithSep, resolved };
-}
-async function resolvePathWithinRoot(params) {
-    return await resolvePathInRoot(await resolveRootContext(params.rootDir), params.relativePath);
-}
-class RootHandle {
-    rootDir;
-    rootReal;
-    rootWithSep;
-    defaults;
-    constructor(context, defaults = {}) {
-        this.rootDir = context.rootDir;
-        this.rootReal = context.rootReal;
-        this.rootWithSep = context.rootWithSep;
-        this.defaults = defaults;
-    }
-    get context() {
-        return {
-            rootDir: this.rootDir,
-            rootReal: this.rootReal,
-            rootWithSep: this.rootWithSep,
-        };
-    }
-    async resolve(relativePath) {
-        return (await resolvePathInRoot(this.context, relativePath)).resolved;
-    }
-    async open(relativePath, options = {}) {
-        return await openFileInRoot(this.context, {
-            relativePath,
-            ...readDefaults(this.defaults),
-            ...options,
-        });
-    }
-    async read(relativePath, options = {}) {
-        return await readFileInRoot(this.context, {
-            relativePath,
-            ...readDefaults(this.defaults),
-            ...options,
-        });
-    }
-    async readBytes(relativePath, options = {}) {
-        return (await this.read(relativePath, options)).buffer;
-    }
-    async readText(relativePath, options = {}) {
-        const { encoding = "utf8", ...readOptions } = options;
-        return (await this.read(relativePath, readOptions)).buffer.toString(encoding);
-    }
-    async readJson(relativePath, options = {}) {
-        return JSON.parse(await this.readText(relativePath, options));
-    }
-    async readAbsolute(filePath, options = {}) {
-        return await readPathInRoot(this.context, {
-            filePath,
-            ...readDefaults(this.defaults),
-            ...options,
-        });
-    }
-    reader(options = {}) {
-        return async (filePath) => {
-            return (await this.readAbsolute(filePath, options)).buffer;
-        };
-    }
-    async openWritable(relativePath, options = {}) {
-        const writeMode = options.writeMode ?? "replace";
-        return await openWritableFileInRoot(this.context, {
-            relativePath,
-            mkdir: this.defaults.mkdir,
-            mode: this.defaults.mode,
-            ...options,
-            append: writeMode === "append",
-            truncateExisting: writeMode === "replace",
-        });
-    }
-    async append(relativePath, data, options = {}) {
-        await appendFileInRoot(this.context, {
-            relativePath,
-            data,
-            mkdir: this.defaults.mkdir,
-            mode: this.defaults.mode,
-            ...options,
-        });
-    }
-    async remove(relativePath) {
-        await removePathInRoot(this.context, relativePath);
-    }
-    async mkdir(relativePath) {
-        await mkdirPathInRoot(this.context, { relativePath });
-    }
-    async ensureRoot() {
-        await mkdirPathInRoot(this.context, { relativePath: "", allowRoot: true });
-    }
-    async write(relativePath, data, options = {}) {
-        await writeFileInRoot(this.context, {
-            relativePath,
-            data,
-            mkdir: this.defaults.mkdir,
-            mode: this.defaults.mode,
-            ...options,
-        });
-    }
-    async create(relativePath, data, options = {}) {
-        await writeFileInRoot(this.context, {
-            relativePath,
-            data,
-            mkdir: this.defaults.mkdir,
-            mode: this.defaults.mode,
-            ...options,
-            overwrite: false,
-        });
-    }
-    async writeJson(relativePath, data, options = {}) {
-        const { replacer, space, trailingNewline = true, ...writeOptions } = options;
-        const json = JSON.stringify(data, replacer, space);
-        await this.write(relativePath, trailingNewline ? `${json}\n` : json, writeOptions);
-    }
-    async createJson(relativePath, data, options = {}) {
-        const { replacer, space, trailingNewline = true, ...writeOptions } = options;
-        const json = JSON.stringify(data, replacer, space);
-        await this.create(relativePath, trailingNewline ? `${json}\n` : json, writeOptions);
-    }
-    async copyIn(relativePath, sourcePath, options = {}) {
-        await copyFileInRoot(this.context, {
-            sourcePath,
-            relativePath,
-            maxBytes: this.defaults.maxBytes,
-            mkdir: this.defaults.mkdir,
-            mode: this.defaults.mode,
-            ...options,
-        });
-    }
-    async exists(relativePath) {
-        try {
-            await this.stat(relativePath);
-            return true;
-        }
-        catch (err) {
-            if (err instanceof FsSafeError && err.code === "not-found") {
-                return false;
-            }
-            throw err;
-        }
-    }
-    async stat(relativePath) {
-        try {
-            return await helperStat(this.rootReal, relativePath);
-        }
-        catch (error) {
-            if (canFallbackFromPythonError(error)) {
-                return await statPathFallback(this.context, relativePath);
-            }
-            throw error;
-        }
-    }
-    async list(relativePath, options = {}) {
-        try {
-            return options.withFileTypes === true
-                ? await helperReaddir(this.rootReal, relativePath, true)
-                : await helperReaddir(this.rootReal, relativePath, false);
-        }
-        catch (error) {
-            if (canFallbackFromPythonError(error)) {
-                return await listPathFallback(this.context, relativePath, options.withFileTypes === true);
-            }
-            throw error;
-        }
-    }
-    async move(fromRelative, toRelative, options = {}) {
-        try {
-            await runPinnedHelper("rename", this.rootReal, {
-                from: fromRelative,
-                overwrite: options.overwrite ?? false,
-                to: toRelative,
-            });
-        }
-        catch (error) {
-            if (canFallbackFromPythonError(error)) {
-                await movePathFallback(this.context, {
-                    fromRelative,
-                    overwrite: options.overwrite ?? false,
-                    toRelative,
-                });
-                return;
-            }
-            throw error;
-        }
-    }
-}
-function readDefaults(defaults) {
-    return {
-        hardlinks: defaults.hardlinks,
-        maxBytes: defaults.maxBytes ?? DEFAULT_ROOT_MAX_BYTES,
-        nonBlockingRead: defaults.nonBlockingRead,
-        symlinks: defaults.symlinks,
-    };
-}
-export async function root(rootDir, defaults = {}) {
-    return new RootHandle(await resolveRootContext(rootDir), defaults);
-}
-async function openFileInRoot(root, params) {
-    const { rootWithSep, resolved } = await resolvePathInRoot(root, params.relativePath);
-    let opened;
-    try {
-        opened = await openVerifiedLocalFile(resolved, {
-            nonBlockingRead: params.nonBlockingRead,
-            symlinks: params.symlinks,
-        });
-    }
-    catch (err) {
-        if (err instanceof FsSafeError) {
-            throw err;
-        }
-        throw err;
-    }
-    if (params.hardlinks !== "allow" && opened.stat.nlink > 1) {
-        await opened.handle.close().catch(() => { });
-        throw new FsSafeError("hardlink", "hardlinked path not allowed");
-    }
-    if (!isPathInside(rootWithSep, opened.realPath)) {
-        await opened.handle.close().catch(() => { });
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
-    }
-    return opened;
-}
-async function readFileInRoot(root, params) {
-    const opened = await openFileInRoot(root, params);
-    try {
-        return await readOpenedFileSafely({ opened, maxBytes: params.maxBytes });
-    }
-    finally {
-        await opened.handle.close().catch(() => { });
-    }
-}
-async function readPathInRoot(root, params) {
-    const rootDir = root.rootDir;
-    const candidatePath = path.isAbsolute(params.filePath)
-        ? path.resolve(params.filePath)
-        : path.resolve(rootDir, params.filePath);
-    const relativePath = path.relative(rootDir, candidatePath);
-    return await readFileInRoot(root, {
-        relativePath,
-        hardlinks: params.hardlinks,
-        maxBytes: params.maxBytes,
-        nonBlockingRead: params.nonBlockingRead,
-        symlinks: params.symlinks,
-    });
-}
-export async function readLocalFileSafely(params) {
-    const opened = await openLocalFileSafely({ filePath: params.filePath });
-    try {
-        return await readOpenedFileSafely({ opened, maxBytes: params.maxBytes });
-    }
-    finally {
-        await opened.handle.close().catch(() => { });
-    }
-}
-export async function openLocalFileSafely(params) {
-    return await openVerifiedLocalFile(params.filePath);
-}
-async function readOpenedFileSafely(params) {
-    if (params.maxBytes !== undefined && params.opened.stat.size > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${params.opened.stat.size})`);
-    }
-    const buffer = await params.opened.handle.readFile();
-    if (params.maxBytes !== undefined && buffer.byteLength > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${buffer.byteLength})`);
-    }
-    return {
-        buffer,
-        realPath: params.opened.realPath,
-        stat: params.opened.stat,
-    };
-}
-function emitWriteBoundaryWarning(reason) {
-    logWarn(`security: fs-safe write boundary warning (${reason})`);
-}
-function buildAtomicWriteTempPath(targetPath) {
-    const dir = path.dirname(targetPath);
-    const base = path.basename(targetPath);
-    return path.join(dir, `.${base}.${process.pid}.${randomUUID()}.tmp`);
-}
-function rootWriteQueueKey(root, relativePath) {
-    return `${root.rootReal}\0${relativePath}`;
-}
-function createMaxBytesTransform(maxBytes) {
-    let bytes = 0;
-    return new Transform({
-        transform(chunk, _encoding, callback) {
-            const buffer = chunk instanceof Buffer ? chunk : Buffer.from(chunk);
-            bytes += buffer.byteLength;
-            if (bytes > maxBytes) {
-                callback(new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`));
-                return;
-            }
-            callback(null, buffer);
-        },
-    });
-}
-function createBoundedReadStream(opened, maxBytes) {
-    const stream = opened.handle.createReadStream();
-    return maxBytes === undefined ? stream : stream.pipe(createMaxBytesTransform(maxBytes));
-}
-async function writeTempFileForAtomicReplace(params) {
-    const tempHandle = await fs.open(params.tempPath, OPEN_WRITE_CREATE_FLAGS, params.mode);
-    try {
-        if (typeof params.data === "string") {
-            await tempHandle.writeFile(params.data, params.encoding ?? "utf8");
-        }
-        else {
-            await tempHandle.writeFile(params.data);
-        }
-        return await tempHandle.stat();
-    }
-    finally {
-        await tempHandle.close().catch(() => { });
-    }
-}
-async function verifyAtomicWriteResult(params) {
-    const opened = await openVerifiedLocalFile(params.targetPath, { hardlinks: "reject" });
-    try {
-        if (!sameFileIdentity(opened.stat, params.expectedIdentity)) {
-            throw new FsSafeError("path-mismatch", "path changed during write");
-        }
-        if (!isPathInside(params.root.rootWithSep, opened.realPath)) {
-            throw new FsSafeError("outside-workspace", "file is outside workspace root");
-        }
-    }
-    finally {
-        await opened.handle.close().catch(() => { });
-    }
-}
-export async function resolveOpenedFileRealPathForHandle(handle, ioPath) {
-    const handleStat = await handle.stat();
-    const fdCandidates = process.platform === "linux"
-        ? [`/proc/self/fd/${handle.fd}`, `/dev/fd/${handle.fd}`]
-        : process.platform === "win32"
-            ? []
-            : [`/dev/fd/${handle.fd}`];
-    for (const fdPath of fdCandidates) {
-        try {
-            const fdRealPath = await fs.realpath(fdPath);
-            const fdRealStat = await fs.stat(fdRealPath);
-            if (sameFileIdentity(handleStat, fdRealStat)) {
-                return fdRealPath;
-            }
-        }
-        catch {
-            // try next fd path
-        }
-    }
-    try {
-        const ioRealPath = await fs.realpath(ioPath);
-        const ioRealStat = await fs.stat(ioRealPath);
-        if (sameFileIdentity(handleStat, ioRealStat)) {
-            return ioRealPath;
-        }
-    }
-    catch (err) {
-        if (!isNotFoundPathError(err)) {
-            throw err;
-        }
-    }
-    const parentResolved = await resolveOpenedFileRealPathFromParent(handleStat, ioPath);
-    if (parentResolved) {
-        return parentResolved;
-    }
-    throw new FsSafeError("path-mismatch", "unable to resolve opened file path");
-}
-async function resolveOpenedFileRealPathFromParent(handleStat, ioPath) {
-    let parentReal;
-    try {
-        parentReal = await fs.realpath(path.dirname(ioPath));
-    }
-    catch (err) {
-        if (isNotFoundPathError(err)) {
-            return null;
-        }
-        throw err;
-    }
-    let entries;
-    try {
-        entries = await fs.readdir(parentReal);
-    }
-    catch (err) {
-        if (isNotFoundPathError(err)) {
-            return null;
-        }
-        throw err;
-    }
-    for (const entry of entries.toSorted()) {
-        const candidatePath = path.join(parentReal, entry);
-        try {
-            const candidateStat = await fs.lstat(candidatePath);
-            if (candidateStat.isFile() && sameFileIdentity(handleStat, candidateStat)) {
-                return await fs.realpath(candidatePath);
-            }
-        }
-        catch (err) {
-            if (!isNotFoundPathError(err)) {
-                throw err;
-            }
-        }
-    }
-    return null;
-}
-async function openWritableFileInRoot(root, params) {
-    const { rootReal, rootWithSep, resolved } = await resolvePathInRoot(root, params.relativePath);
-    try {
-        await assertNoPathAliasEscape({
-            absolutePath: resolved,
-            rootPath: rootReal,
-            boundaryLabel: "root",
-        });
-    }
-    catch (err) {
-        throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
-    }
-    if (params.mkdir !== false) {
-        await fs.mkdir(path.dirname(resolved), { recursive: true });
-    }
-    let ioPath = resolved;
-    try {
-        const resolvedRealPath = await fs.realpath(resolved);
-        if (!isPathInside(rootWithSep, resolvedRealPath)) {
-            throw new FsSafeError("outside-workspace", "file is outside workspace root");
-        }
-        ioPath = resolvedRealPath;
-    }
-    catch (err) {
-        if (err instanceof FsSafeError) {
-            throw err;
-        }
-        if (!isNotFoundPathError(err)) {
-            throw err;
-        }
-    }
-    const mode = params.mode ?? 0o600;
-    let handle;
-    let createdForWrite = false;
-    const existingFlags = params.append ? OPEN_APPEND_EXISTING_FLAGS : OPEN_WRITE_EXISTING_FLAGS;
-    const createFlags = params.append ? OPEN_APPEND_CREATE_FLAGS : OPEN_WRITE_CREATE_FLAGS;
-    try {
-        try {
-            handle = await fs.open(ioPath, existingFlags, mode);
-        }
-        catch (err) {
-            if (!isNotFoundPathError(err)) {
-                throw err;
-            }
-            handle = await fs.open(ioPath, createFlags, mode);
-            createdForWrite = true;
-        }
-    }
-    catch (err) {
-        if (isNotFoundPathError(err)) {
-            throw new FsSafeError("not-found", "file not found");
-        }
-        if (isSymlinkOpenError(err)) {
-            throw new FsSafeError("symlink", "symlink open blocked", { cause: err });
-        }
-        throw err;
-    }
-    let realPathForCleanup = null;
-    try {
-        const stat = await handle.stat();
-        if (!stat.isFile()) {
-            throw new FsSafeError("invalid-path", "path is not a regular file under root");
-        }
-        if (stat.nlink > 1) {
-            throw new FsSafeError("hardlink", "hardlinked path not allowed");
-        }
-        try {
-            const lstat = await fs.lstat(ioPath);
-            if (lstat.isSymbolicLink() || !lstat.isFile()) {
-                throw new FsSafeError(lstat.isSymbolicLink() ? "symlink" : "not-file", "path is not a regular file under root");
-            }
-            if (!sameFileIdentity(stat, lstat)) {
-                throw new FsSafeError("path-mismatch", "path changed during write");
-            }
-        }
-        catch (err) {
-            if (!isNotFoundPathError(err)) {
-                throw err;
-            }
-        }
-        const realPath = await resolveOpenedFileRealPathForHandle(handle, ioPath);
-        realPathForCleanup = realPath;
-        const realStat = await fs.stat(realPath);
-        if (!sameFileIdentity(stat, realStat)) {
-            throw new FsSafeError("path-mismatch", "path mismatch");
-        }
-        if (realStat.nlink > 1) {
-            throw new FsSafeError("hardlink", "hardlinked path not allowed");
-        }
-        if (!isPathInside(rootWithSep, realPath)) {
-            throw new FsSafeError("outside-workspace", "file is outside workspace root");
-        }
-        // Truncate only after boundary and identity checks complete. This avoids
-        // irreversible side effects if a symlink target changes before validation.
-        if (params.append !== true && params.truncateExisting !== false && !createdForWrite) {
-            await handle.truncate(0);
-        }
-        return {
-            handle,
-            createdForWrite,
-            realPath,
-            stat,
-            [Symbol.asyncDispose]: async () => {
-                await closeHandleForDispose(handle);
-            },
-        };
-    }
-    catch (err) {
-        const cleanupCreatedPath = createdForWrite && err instanceof FsSafeError;
-        const cleanupPath = realPathForCleanup ?? ioPath;
-        await handle.close().catch(() => { });
-        if (cleanupCreatedPath) {
-            await fs.rm(cleanupPath, { force: true }).catch(() => { });
-        }
-        throw err;
-    }
-}
-async function appendFileInRoot(root, params) {
-    const target = await openWritableFileInRoot(root, {
-        relativePath: params.relativePath,
-        mkdir: params.mkdir,
-        mode: params.mode,
-        truncateExisting: false,
-        append: true,
-    });
-    try {
-        let prefix = "";
-        if (params.prependNewlineIfNeeded === true &&
-            !target.createdForWrite &&
-            target.stat.size > 0 &&
-            ((typeof params.data === "string" && !params.data.startsWith("\n")) ||
-                (Buffer.isBuffer(params.data) && params.data.length > 0 && params.data[0] !== 0x0a))) {
-            const lastByte = Buffer.alloc(1);
-            const { bytesRead } = await target.handle.read(lastByte, 0, 1, target.stat.size - 1);
-            if (bytesRead === 1 && lastByte[0] !== 0x0a) {
-                prefix = "\n";
-            }
-        }
-        if (typeof params.data === "string") {
-            await target.handle.appendFile(`${prefix}${params.data}`, params.encoding ?? "utf8");
-            return;
-        }
-        const payload = prefix.length > 0 ? Buffer.concat([Buffer.from(prefix, "utf8"), params.data]) : params.data;
-        await target.handle.appendFile(payload);
-    }
-    finally {
-        await target.handle.close().catch(() => { });
-    }
-}
-async function removePathInRoot(root, relativePath) {
-    const resolved = await resolvePinnedRemovePathInRoot(root, relativePath);
-    if (process.platform === "win32") {
-        await removePathFallback(resolved);
-        return;
-    }
-    try {
-        await runPinnedPathHelper({
-            operation: "remove",
-            rootPath: resolved.rootReal,
-            relativePath: resolved.relativePosix,
-        });
-    }
-    catch (error) {
-        if (isPinnedPathHelperSpawnError(error)) {
-            await removePathFallback(resolved);
-            return;
-        }
-        throw normalizePinnedPathError(error);
-    }
-}
-async function mkdirPathInRoot(root, params) {
-    const resolved = await resolvePinnedPathInRoot(root, params);
-    if (process.platform === "win32") {
-        await mkdirPathFallback(resolved);
-        return;
-    }
-    try {
-        await runPinnedPathHelper({
-            operation: "mkdirp",
-            rootPath: resolved.rootReal,
-            relativePath: resolved.relativePosix,
-        });
-    }
-    catch (error) {
-        if (isPinnedPathHelperSpawnError(error)) {
-            await mkdirPathFallback(resolved);
-            return;
-        }
-        throw normalizePinnedPathError(error);
-    }
-}
-async function writeFileInRoot(root, params) {
-    if (process.platform === "win32") {
-        await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
-            await writeFileFallback(root, params);
-        });
-        return;
-    }
-    const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode);
-    await serializePathWrite(pinned.targetPath, async () => {
-        let identity;
-        try {
-            identity = await runPinnedWriteHelper({
-                rootPath: pinned.rootReal,
-                relativeParentPath: pinned.relativeParentPath,
-                basename: pinned.basename,
-                mkdir: params.mkdir !== false,
-                mode: params.mode ?? pinned.mode,
-                overwrite: params.overwrite,
-                input: {
-                    kind: "buffer",
-                    data: params.data,
-                    encoding: params.encoding,
-                },
-            });
-        }
-        catch (error) {
-            if (params.overwrite === false && isAlreadyExistsError(error)) {
-                throw new FsSafeError("already-exists", "file already exists", {
-                    cause: error instanceof Error ? error : undefined,
-                });
-            }
-            throw normalizePinnedWriteError(error);
-        }
-        try {
-            await verifyAtomicWriteResult({
-                root,
-                targetPath: pinned.targetPath,
-                expectedIdentity: identity,
-            });
-        }
-        catch (err) {
-            emitWriteBoundaryWarning(`post-write verification failed: ${String(err)}`);
-            throw err;
-        }
-    });
-}
-async function copyFileInRoot(root, params) {
-    const source = await openVerifiedLocalFile(params.sourcePath, {
-        hardlinks: params.sourceHardlinks,
-    });
-    if (params.maxBytes !== undefined && source.stat.size > params.maxBytes) {
-        await source.handle.close().catch(() => { });
-        throw new FsSafeError("too-large", `file exceeds limit of ${params.maxBytes} bytes (got ${source.stat.size})`);
-    }
-    try {
-        if (process.platform === "win32") {
-            await serializePathWrite(rootWriteQueueKey(root, params.relativePath), async () => {
-                await copyFileFallback(root, params, source);
-            });
-            return;
-        }
-        const pinned = await resolvePinnedWriteTargetInRoot(root, params.relativePath, params.mode);
-        await serializePathWrite(pinned.targetPath, async () => {
-            let identity;
-            try {
-                if (getFsSafePythonConfig().mode === "off") {
-                    await copyFileFallback(root, params, source);
-                    return;
-                }
-                identity = await runPinnedCopyHelper({
-                    rootPath: pinned.rootReal,
-                    relativeParentPath: pinned.relativeParentPath,
-                    basename: pinned.basename,
-                    mkdir: params.mkdir !== false,
-                    mode: pinned.mode,
-                    overwrite: true,
-                    maxBytes: params.maxBytes,
-                    sourcePath: source.realPath,
-                    sourceIdentity: { dev: source.stat.dev, ino: source.stat.ino },
-                });
-            }
-            catch (error) {
-                if (canFallbackFromPythonError(error)) {
-                    await copyFileFallback(root, params, source);
-                    return;
-                }
-                throw normalizePinnedWriteError(error);
-            }
-            try {
-                await verifyAtomicWriteResult({
-                    root,
-                    targetPath: pinned.targetPath,
-                    expectedIdentity: identity,
-                });
-            }
-            catch (err) {
-                emitWriteBoundaryWarning(`post-copy verification failed: ${String(err)}`);
-                throw err;
-            }
-        });
-    }
-    finally {
-        await source.handle.close().catch(() => { });
-    }
-}
-async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode) {
-    const { rootReal, rootWithSep, resolved } = await resolvePathInRoot(root, relativePath);
-    try {
-        await assertNoPathAliasEscape({
-            absolutePath: resolved,
-            rootPath: rootReal,
-            boundaryLabel: "root",
-        });
-    }
-    catch (err) {
-        throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
-    }
-    const relativeResolved = path.relative(rootReal, resolved);
-    if (relativeResolved.startsWith("..") || path.isAbsolute(relativeResolved)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
-    }
-    const relativePosix = relativeResolved
-        ? relativeResolved.split(path.sep).join(path.posix.sep)
-        : "";
-    const basename = path.posix.basename(relativePosix);
-    if (!basename || basename === "." || basename === "/") {
-        throw new FsSafeError("invalid-path", "invalid target path");
-    }
-    let mode = requestedMode ?? 0o600;
-    try {
-        const opened = await openFileInRoot(root, {
-            relativePath,
-            hardlinks: "reject",
-            nonBlockingRead: true,
-        });
-        try {
-            mode = requestedMode ?? (opened.stat.mode & 0o777);
-            if (!isPathInside(rootWithSep, opened.realPath)) {
-                throw new FsSafeError("outside-workspace", "file is outside workspace root");
-            }
-        }
-        finally {
-            await opened.handle.close().catch(() => { });
-        }
-    }
-    catch (err) {
-        if (!(err instanceof FsSafeError) || err.code !== "not-found") {
-            throw err;
-        }
-    }
-    return {
-        rootReal,
-        targetPath: resolved,
-        relativeParentPath: path.posix.dirname(relativePosix) === "." ? "" : path.posix.dirname(relativePosix),
-        basename,
-        mode: mode || 0o600,
-    };
-}
-async function resolvePinnedPathInRoot(root, params) {
-    const resolved = await resolvePinnedRootPathInRoot(root, {
-        relativePath: params.relativePath,
-        policy: PATH_ALIAS_POLICIES.strict,
-    });
-    const relativeResolved = path.relative(resolved.rootReal, resolved.canonicalPath);
-    if ((relativeResolved === "" || relativeResolved === ".") && params.allowRoot === true) {
-        return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix: "" };
-    }
-    if (relativeResolved === "" ||
-        relativeResolved === "." ||
-        relativeResolved.startsWith("..") ||
-        path.isAbsolute(relativeResolved)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
-    }
-    const relativePosix = relativeResolved.split(path.sep).join(path.posix.sep);
-    if (!isPathInside(resolved.rootWithSep, resolved.canonicalPath)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
-    }
-    return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix };
-}
-async function resolvePinnedRemovePathInRoot(root, relativePath) {
-    const resolved = await resolvePinnedRootPathInRoot(root, {
-        relativePath,
-        policy: PATH_ALIAS_POLICIES.unlinkTarget,
-    });
-    const relativeResolved = path.relative(resolved.rootReal, resolved.canonicalPath);
-    if (relativeResolved === "" ||
-        relativeResolved === "." ||
-        relativeResolved.startsWith("..") ||
-        path.isAbsolute(relativeResolved)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
-    }
-    const relativePosix = relativeResolved.split(path.sep).join(path.posix.sep);
-    if (!isPathInside(resolved.rootWithSep, resolved.canonicalPath)) {
-        throw new FsSafeError("outside-workspace", "file is outside workspace root");
-    }
-    const parentRelative = path.posix.dirname(relativePosix);
-    if (parentRelative === "." || parentRelative === "") {
-        return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix };
-    }
-    return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix };
-}
-async function resolvePinnedRootPathInRoot(root, params) {
-    const rootReal = root.rootReal;
-    let resolved;
-    try {
-        resolved = await resolveRootPath({
-            absolutePath: path.resolve(rootReal, await expandRelativePathWithHome(params.relativePath)),
-            rootPath: rootReal,
-            rootCanonicalPath: rootReal,
-            boundaryLabel: "root",
-            policy: params.policy,
-        });
-    }
-    catch (err) {
-        throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
-    }
-    const rootWithSep = ensureTrailingSep(resolved.rootCanonicalPath);
-    return {
-        rootReal: resolved.rootCanonicalPath,
-        rootWithSep,
-        canonicalPath: resolved.canonicalPath,
-    };
-}
-function normalizePinnedWriteError(error) {
-    if (error instanceof FsSafeError) {
-        return error;
-    }
-    return new FsSafeError("invalid-path", "path is not a regular file under root", {
-        cause: error instanceof Error ? error : undefined,
-    });
-}
-function isAlreadyExistsError(error) {
-    return hasNodeErrorCode(error, "EEXIST") || /File exists|EEXIST/i.test(String(error));
-}
-function normalizePinnedPathError(error) {
-    if (error instanceof FsSafeError) {
-        return error;
-    }
-    return new FsSafeError("path-alias", "path is not under root", {
-        cause: error instanceof Error ? error : undefined,
-    });
-}
-async function removePathFallback(resolved) {
-    await fs.rm(resolved.resolved);
-}
-async function mkdirPathFallback(resolved) {
-    await fs.mkdir(resolved.resolved, { recursive: true });
-}
-function pathStatFromStats(stat) {
-    return {
-        dev: Number(stat.dev),
-        gid: Number(stat.gid),
-        ino: Number(stat.ino),
-        isDirectory: stat.isDirectory(),
-        isFile: stat.isFile(),
-        isSymbolicLink: stat.isSymbolicLink(),
-        mode: stat.mode,
-        mtimeMs: stat.mtimeMs,
-        nlink: stat.nlink,
-        size: stat.size,
-        uid: stat.uid,
-    };
-}
-async function statPathFallback(root, relativePath) {
-    const resolved = await resolvePinnedPathInRoot(root, { relativePath, allowRoot: true });
-    try {
-        return pathStatFromStats(await fs.lstat(resolved.resolved));
-    }
-    catch (error) {
-        if (isNotFoundPathError(error)) {
-            throw new FsSafeError("not-found", "file not found", {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        throw error;
-    }
-}
-async function listPathFallback(root, relativePath, withFileTypes) {
-    const resolved = await resolvePinnedPathInRoot(root, { relativePath, allowRoot: true });
-    try {
-        const names = await fs.readdir(resolved.resolved);
-        const sortedNames = names.toSorted();
-        if (!withFileTypes) {
-            return sortedNames;
-        }
-        const entries = [];
-        for (const name of sortedNames) {
-            entries.push({
-                name,
-                ...pathStatFromStats(await fs.lstat(path.join(resolved.resolved, name))),
-            });
-        }
-        return entries;
-    }
-    catch (error) {
-        if (isNotFoundPathError(error)) {
-            throw new FsSafeError("not-found", "directory not found", {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        throw error;
-    }
-}
-async function movePathFallback(root, params) {
-    const source = await resolvePathInRoot(root, params.fromRelative);
-    await resolvePinnedRootPathInRoot(root, {
-        relativePath: params.fromRelative,
-        policy: PATH_ALIAS_POLICIES.strict,
-    });
-    const target = await resolvePathInRoot(root, params.toRelative);
-    await resolvePinnedRootPathInRoot(root, {
-        relativePath: params.toRelative,
-        policy: PATH_ALIAS_POLICIES.unlinkTarget,
-    });
-    try {
-        await assertNoPathAliasEscape({
-            absolutePath: target.resolved,
-            rootPath: target.rootReal,
-            boundaryLabel: "root",
-        });
-    }
-    catch (error) {
-        throw new FsSafeError("path-alias", "path alias escape blocked", {
-            cause: error instanceof Error ? error : undefined,
-        });
-    }
-    let sourceStat;
-    try {
-        sourceStat = await fs.lstat(source.resolved);
-    }
-    catch (error) {
-        if (isNotFoundPathError(error)) {
-            throw new FsSafeError("not-found", "file not found", {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        throw error;
-    }
-    if (sourceStat.isSymbolicLink()) {
-        throw new FsSafeError("symlink", "symlink not allowed");
-    }
-    if (sourceStat.isFile() && sourceStat.nlink > 1) {
-        throw new FsSafeError("hardlink", "hardlinked path not allowed");
-    }
-    if (!params.overwrite) {
-        try {
-            await fs.lstat(target.resolved);
-            throw new FsSafeError("already-exists", "destination exists");
-        }
-        catch (error) {
-            if (error instanceof FsSafeError) {
-                throw error;
-            }
-            if (!isNotFoundPathError(error)) {
-                throw error;
-            }
-        }
-    }
-    try {
-        await fs.rename(source.resolved, target.resolved);
-    }
-    catch (error) {
-        if (isNotFoundPathError(error)) {
-            throw new FsSafeError("not-found", "file not found", {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        if (hasNodeErrorCode(error, "EEXIST")) {
-            throw new FsSafeError("already-exists", "destination exists", {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        throw error;
-    }
-}
-async function writeFileFallback(root, params) {
-    if (params.overwrite === false) {
-        await writeMissingFileFallback(root, params);
-        return;
-    }
-    const target = await openWritableFileInRoot(root, {
-        relativePath: params.relativePath,
-        mkdir: params.mkdir,
-        mode: params.mode,
-        truncateExisting: false,
-    });
-    const destinationPath = target.realPath;
-    const mode = params.mode ?? (target.stat.mode & 0o777);
-    await target.handle.close().catch(() => { });
-    let tempPath = null;
-    let unregisterTempPath = null;
-    try {
-        tempPath = buildAtomicWriteTempPath(destinationPath);
-        unregisterTempPath = registerTempPathForExit(tempPath);
-        const writtenStat = await writeTempFileForAtomicReplace({
-            tempPath,
-            data: params.data,
-            encoding: params.encoding,
-            mode: mode || 0o600,
-        });
-        await fs.rename(tempPath, destinationPath);
-        tempPath = null;
-        unregisterTempPath();
-        unregisterTempPath = null;
-        try {
-            await verifyAtomicWriteResult({
-                root,
-                targetPath: destinationPath,
-                expectedIdentity: writtenStat,
-            });
-        }
-        catch (err) {
-            emitWriteBoundaryWarning(`post-write verification failed: ${String(err)}`);
-            throw err;
-        }
-    }
-    finally {
-        if (tempPath) {
-            await fs.rm(tempPath, { force: true }).catch(() => { });
-        }
-        unregisterTempPath?.();
-    }
-}
-async function writeMissingFileFallback(root, params) {
-    const { rootReal, resolved } = await resolvePathInRoot(root, params.relativePath);
-    try {
-        await assertNoPathAliasEscape({
-            absolutePath: resolved,
-            rootPath: rootReal,
-            boundaryLabel: "root",
-        });
-    }
-    catch (err) {
-        throw new FsSafeError("path-alias", "path alias escape blocked", { cause: err });
-    }
-    if (params.mkdir !== false) {
-        await fs.mkdir(path.dirname(resolved), { recursive: true });
-    }
-    let handle = null;
-    let created = false;
-    try {
-        handle = await fs.open(resolved, OPEN_WRITE_CREATE_FLAGS, params.mode ?? 0o600);
-        created = true;
-        if (typeof params.data === "string") {
-            await handle.writeFile(params.data, params.encoding ?? "utf8");
-        }
-        else {
-            await handle.writeFile(params.data);
-        }
-        const writtenStat = await handle.stat();
-        await handle.close();
-        handle = null;
-        await verifyAtomicWriteResult({
-            root,
-            targetPath: resolved,
-            expectedIdentity: writtenStat,
-        });
-        created = false;
-    }
-    catch (err) {
-        if (hasNodeErrorCode(err, "EEXIST")) {
-            throw new FsSafeError("already-exists", "file already exists", {
-                cause: err instanceof Error ? err : undefined,
-            });
-        }
-        throw err;
-    }
-    finally {
-        await handle?.close().catch(() => undefined);
-        if (created) {
-            await fs.rm(resolved, { force: true }).catch(() => undefined);
-        }
-    }
-}
-async function copyFileFallback(root, params, source) {
-    let target = null;
-    let sourceClosedByStream = false;
-    let targetClosedByUs = false;
-    let tempHandle = null;
-    let tempPath = null;
-    let unregisterTempPath = null;
-    let tempClosedByStream = false;
-    try {
-        target = await openWritableFileInRoot(root, {
-            relativePath: params.relativePath,
-            mkdir: params.mkdir,
-            mode: params.mode,
-            truncateExisting: false,
-        });
-        const destinationPath = target.realPath;
-        const mode = params.mode ?? (target.stat.mode & 0o777);
-        await target.handle.close().catch(() => { });
-        targetClosedByUs = true;
-        tempPath = buildAtomicWriteTempPath(destinationPath);
-        unregisterTempPath = registerTempPathForExit(tempPath);
-        tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, mode || 0o600);
-        const sourceStream = createBoundedReadStream(source, params.maxBytes);
-        const targetStream = tempHandle.createWriteStream();
-        sourceStream.once("close", () => {
-            sourceClosedByStream = true;
-        });
-        targetStream.once("close", () => {
-            tempClosedByStream = true;
-        });
-        await pipeline(sourceStream, targetStream);
-        const writtenStat = await fs.stat(tempPath);
-        if (!tempClosedByStream) {
-            await tempHandle.close().catch(() => { });
-            tempClosedByStream = true;
-        }
-        tempHandle = null;
-        await fs.rename(tempPath, destinationPath);
-        tempPath = null;
-        unregisterTempPath();
-        unregisterTempPath = null;
-        try {
-            await verifyAtomicWriteResult({
-                root,
-                targetPath: destinationPath,
-                expectedIdentity: writtenStat,
-            });
-        }
-        catch (err) {
-            emitWriteBoundaryWarning(`post-copy verification failed: ${String(err)}`);
-            throw err;
-        }
-    }
-    catch (err) {
-        if (target?.createdForWrite) {
-            await fs.rm(target.realPath, { force: true }).catch(() => { });
-        }
-        throw err;
-    }
-    finally {
-        if (!sourceClosedByStream) {
-            await source.handle.close().catch(() => { });
-        }
-        if (tempHandle && !tempClosedByStream) {
-            await tempHandle.close().catch(() => { });
-        }
-        if (tempPath) {
-            await fs.rm(tempPath, { force: true }).catch(() => { });
-        }
-        unregisterTempPath?.();
-        if (target && !targetClosedByUs) {
-            await target.handle.close().catch(() => { });
-        }
-    }
-}
+export { DEFAULT_ROOT_MAX_BYTES, openLocalFileSafely, readLocalFileSafely, resolveOpenedFileRealPathForHandle, root, } from "./root-impl.js";