Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

47.0 KB
Raw Blame
import { randomUUID } from "node:crypto";
import { constants as fsConstants } from "node:fs";
import fs from "node:fs/promises";
import path from "node:path";
import { pipeline } from "node:stream/promises";
import { createBoundedReadStream } from "./bounded-read-stream.js";
import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard } from "./directory-guard.js";
import { FsSafeError } from "./errors.js";
import { syncDirectoryBestEffort } from "./fsync.js";
import { sameFileIdentity } from "./file-identity.js";
import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
import { withAsyncDirectoryGuards } from "./guarded-mutation.js";
import { assertMutationNotDenied, mergeDenyMutationPolicies, } from "./deny-mutations.js";
import { resolveOpenedFileRealPathForHandle } from "./opened-realpath.js";
import { isPinnedPathHelperSpawnError, runPinnedPathHelper } from "./pinned-path.js";
import { runPinnedCopyHelper, runPinnedWriteHelper } from "./pinned-write.js";
import { canFallbackFromPythonError, getFsSafePythonConfig } from "./pinned-python-config.js";
import { assertNoPathAliasEscape, PATH_ALIAS_POLICIES } from "./path-policy.js";
import { assertNoNulPathInput, assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isPathInside, isSymlinkOpenError, } from "./path.js";
import { readOpenedFileSafely } from "./read-opened-file.js";
import { helperReaddir, helperStat, runPinnedHelper, } from "./pinned-helper.js";
import { pathStatFromStats } from "./path-stat.js";
import { resolveRootPath } from "./root-path.js";
import { assertValidRootRelativePath, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, } from "./root-context.js";
import { isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, } from "./root-errors.js";
import { getFsSafeTestHooks } from "./test-hooks.js";
import { stringifyJsonDocument } from "./json-stringify.js";
import { registerTempPathForExit } from "./temp-cleanup.js";
import { serializePathWrite } from "./write-queue.js";
export { resolveOpenedFileRealPathForHandle } from "./opened-realpath.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 openResult(params) {
    return {
        handle: params.handle,
        realPath: params.realPath,
        stat: params.stat,
        [Symbol.asyncDispose]: () => params.handle.close().catch(() => undefined),
    };
}
async function openVerifiedLocalFile(filePath, options) {
    assertNoUnsafeDeviceReadPath(filePath);
    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;
    }
}
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,
            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
            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,
            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
        });
    }
    async remove(relativePath, options = {}) {
        assertValidRootRelativePath(relativePath);
        await removePathInRoot(this.context, {
            relativePath,
            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
        });
    }
    async mkdir(relativePath, options = {}) {
        assertValidRootRelativePath(relativePath);
        await mkdirPathInRoot(this.context, {
            relativePath,
            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
        });
    }
    async ensureRoot(options = {}) {
        await mkdirPathInRoot(this.context, {
            relativePath: "",
            allowRoot: true,
            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
        });
    }
    async write(relativePath, data, options = {}) {
        await writeFileInRoot(this.context, {
            relativePath,
            data,
            mkdir: this.defaults.mkdir,
            mode: this.defaults.mode,
            ...options,
            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
        });
    }
    async create(relativePath, data, options = {}) {
        await writeFileInRoot(this.context, {
            relativePath,
            data,
            mkdir: this.defaults.mkdir,
            mode: this.defaults.mode,
            ...options,
            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
            overwrite: false,
        });
    }
    async writeJson(relativePath, data, options = {}) {
        const { replacer, space, trailingNewline = true, ...writeOptions } = options;
        const json = stringifyJsonDocument(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 = stringifyJsonDocument(data, replacer, space);
        await this.create(relativePath, trailingNewline ? `${json}\n` : json, writeOptions);
    }
    async copyIn(relativePath, sourcePath, options = {}) {
        assertValidRootRelativePath(relativePath);
        await copyFileInRoot(this.context, {
            sourcePath,
            relativePath,
            maxBytes: this.defaults.maxBytes,
            mkdir: this.defaults.mkdir,
            mode: this.defaults.mode,
            ...options,
            denyMutations: mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations),
        });
    }
    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) {
        assertValidRootRelativePath(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 = {}) {
        assertValidRootRelativePath(relativePath);
        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 = {}) {
        assertValidRootRelativePath(fromRelative);
        assertValidRootRelativePath(toRelative);
        const denyMutations = mergeDenyMutationPolicies(this.defaults.denyMutations, options.denyMutations);
        await assertMoveMutationAllowed(this.context, {
            fromRelative,
            toRelative,
            denyMutations,
        });
        try {
            await runPinnedHelper("rename", this.rootReal, {
                from: fromRelative,
                overwrite: options.overwrite ?? false,
                to: toRelative,
            });
        }
        catch (error) {
            if (canFallbackFromPythonError(error)) {
                await movePathFallback(this.context, {
                    fromRelative,
                    denyMutations,
                    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) {
    assertNoNulPathInput(params.filePath, "file path contains a NUL byte");
    return await openVerifiedLocalFile(params.filePath);
}
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}`;
}
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(() => { });
    }
}
async function openWritableFileInRoot(root, params) {
    const { rootReal, rootWithSep, resolved } = await resolvePathInRoot(root, params.relativePath);
    await assertMutationNotDenied(resolved, params.denyMutations);
    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) {
        const parentGuard = await createNearestExistingDirectoryGuard(rootReal, path.dirname(resolved));
        await withAsyncDirectoryGuards([parentGuard], async () => {
            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 });
        }
        if (hasNodeErrorCode(err, "EISDIR")) {
            throw new FsSafeError("not-file", "not a file", { 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]: () => handle.close().catch(() => undefined),
        };
    }
    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,
        denyMutations: params.denyMutations,
        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");
        }
        else {
            const payload = prefix.length > 0 ? Buffer.concat([Buffer.from(prefix, "utf8"), params.data]) : params.data;
            await target.handle.appendFile(payload);
        }
        await target.handle.sync();
        if (target.createdForWrite) {
            await syncDirectoryBestEffort(path.dirname(target.realPath));
        }
    }
    finally {
        await target.handle.close().catch(() => { });
    }
}
async function removePathInRoot(root, params) {
    const resolved = await resolvePinnedRemovePathInRoot(root, params.relativePath, params.denyMutations);
    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, params.denyMutations);
    await serializePathWrite(pinned.targetPath, async () => {
        await commitPinnedWriteInRoot(root, pinned, params);
    });
}
async function commitPinnedWriteInRoot(root, pinned, params) {
    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) {
    assertValidRootRelativePath(params.relativePath);
    assertNoNulPathInput(params.sourcePath, "source path contains a NUL byte");
    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, params.denyMutations);
        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, denyMutations) {
    const { rootReal, rootWithSep, resolved } = await resolvePathInRoot(root, relativePath);
    await assertMutationNotDenied(resolved, denyMutations);
    try {
        await assertNoPathAliasEscape({
            absolutePath: resolved,
            rootPath: rootReal,
            boundaryLabel: "root",
        });
    }
    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 (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) {
    return await resolvePinnedOperationPathInRoot(root, {
        allowRoot: params.allowRoot,
        denyMutations: params.denyMutations,
        protectDenyMutationAncestors: false,
        relativePath: params.relativePath,
        policy: PATH_ALIAS_POLICIES.strict,
    });
}
async function resolvePinnedRemovePathInRoot(root, relativePath, denyMutations) {
    return await resolvePinnedOperationPathInRoot(root, {
        denyMutations,
        protectDenyMutationAncestors: true,
        relativePath,
        policy: PATH_ALIAS_POLICIES.unlinkTarget,
    });
}
async function resolvePinnedOperationPathInRoot(root, params) {
    const resolved = await resolvePinnedRootPathInRoot(root, {
        relativePath: params.relativePath,
        policy: params.policy,
    });
    const relativeResolved = path.relative(resolved.rootReal, resolved.canonicalPath);
    if ((relativeResolved === "" || relativeResolved === ".") && params.allowRoot === true) {
        await assertMutationNotDenied(resolved.canonicalPath, params.denyMutations);
        return { rootReal: resolved.rootReal, resolved: resolved.canonicalPath, relativePosix: "" };
    }
    const firstSegment = relativeResolved.split(path.sep)[0];
    if (relativeResolved === "" ||
        relativeResolved === "." ||
        firstSegment === ".." ||
        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");
    }
    await assertMutationNotDenied(resolved.canonicalPath, params.denyMutations, {
        protectAncestors: params.protectDenyMutationAncestors,
    });
    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,
    };
}
async function removePathFallback(resolved) {
    const guard = await createAsyncDirectoryGuard(path.dirname(resolved.resolved));
    await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("remove", resolved.resolved);
    await assertAsyncDirectoryGuard(guard);
    await ((await fs.lstat(resolved.resolved)).isDirectory() ? fs.rmdir(resolved.resolved) : fs.rm(resolved.resolved));
    await assertAsyncDirectoryGuard(guard).catch(() => undefined);
}
async function mkdirPathFallback(resolved) {
    await mkdirPathComponentsWithGuards({
        rootReal: resolved.rootReal, targetPath: resolved.resolved,
        beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
    });
}
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 assertMoveMutationAllowed(root, params) {
    const source = await resolvePathInRoot(root, params.fromRelative);
    await assertMutationNotDenied(source.resolved, params.denyMutations, { protectAncestors: true });
    const target = await resolvePathInRoot(root, params.toRelative);
    await assertMutationNotDenied(target.resolved, params.denyMutations, { protectAncestors: true });
}
async function movePathFallback(root, params) {
    const source = await resolvePathInRoot(root, params.fromRelative);
    await assertMutationNotDenied(source.resolved, params.denyMutations, { protectAncestors: true });
    await resolvePinnedRootPathInRoot(root, {
        relativePath: params.fromRelative,
        policy: PATH_ALIAS_POLICIES.strict,
    });
    const target = await resolvePathInRoot(root, params.toRelative);
    await assertMutationNotDenied(target.resolved, params.denyMutations, { protectAncestors: true });
    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 && sourceStat.isDirectory()) {
        throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
    }
    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;
            }
        }
    }
    const sourceParentGuard = await createAsyncDirectoryGuard(path.dirname(source.resolved));
    const targetParentGuard = await createNearestExistingDirectoryGuard(target.rootReal, path.dirname(target.resolved));
    await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("move", target.resolved);
    await assertAsyncDirectoryGuard(sourceParentGuard);
    await assertAsyncDirectoryGuard(targetParentGuard);
    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;
    }
    await assertAsyncDirectoryGuard(targetParentGuard).catch(() => undefined);
}
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,
        denyMutations: params.denyMutations,
        truncateExisting: false,
    });
    const destinationPath = target.realPath;
    const mode = params.mode ?? (target.stat.mode & 0o777);
    await target.handle.close().catch(() => { });
    const destinationGuard = await createAsyncDirectoryGuard(path.dirname(destinationPath));
    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,
        });
        const commitTempPath = tempPath;
        await withAsyncDirectoryGuards([destinationGuard], async () => {
            await fs.rename(commitTempPath, 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);
    await assertMutationNotDenied(resolved, params.denyMutations);
    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 });
    }
    const parentGuard = await createAsyncDirectoryGuard(path.dirname(resolved));
    let created = false;
    try {
        const { handle, writtenStat } = await withAsyncDirectoryGuards([parentGuard], async () => {
            const handle = await fs.open(resolved, OPEN_WRITE_CREATE_FLAGS, params.mode ?? 0o600);
            created = true;
            try {
                if (typeof params.data === "string") {
                    await handle.writeFile(params.data, params.encoding ?? "utf8");
                }
                else {
                    await handle.writeFile(params.data);
                }
                return { handle, writtenStat: await handle.stat() };
            }
            catch (error) {
                await handle.close().catch(() => undefined);
                throw error;
            }
        }, {
            onPostGuardFailure: async ({ handle }) => {
                created = false; // Parent is untrusted now; skip outer path cleanup by name.
                await handle.close().catch(() => undefined);
            },
        });
        await handle.close();
        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 {
        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,
            denyMutations: params.denyMutations,
            truncateExisting: false,
        });
        const destinationPath = target.realPath;
        const mode = params.mode ?? (target.stat.mode & 0o777);
        await target.handle.close().catch(() => { });
        targetClosedByUs = true;
        const destinationGuard = await createAsyncDirectoryGuard(path.dirname(destinationPath));
        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;
        const commitTempPath = tempPath;
        await withAsyncDirectoryGuards([destinationGuard], async () => {
            await fs.rename(commitTempPath, 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(() => { });
        }
    }
}