musonda 1.0.0

package/dist/security/fileSandbox.js

@@ -0,0 +1,779 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getMusondaHomeDir } from '../config/paths.js';
+import { logger } from '../utils/logger.js';
+export class SandboxSecurityError extends Error {
+    code;
+    path;
+    details;
+    constructor(message, code = 'SANDBOX_SECURITY_VIOLATION', extra) {
+        super(message);
+        this.name = 'SandboxSecurityError';
+        this.code = code;
+        this.path = extra?.path;
+        this.details = extra?.details;
+    }
+}
+/**
+ * Match a string against a glob pattern.
+ * Supports `**` (recursive directories), `*` (any chars within path segment), and `?`.
+ */
+export function matchGlob(str, pattern) {
+    const normStr = str.replace(/\\/g, '/').replace(/^\.\//, '');
+    const normPattern = pattern.replace(/\\/g, '/').replace(/^\.\//, '');
+    let regexStr = '^';
+    let i = 0;
+    while (i < normPattern.length) {
+        const c = normPattern[i];
+        if (c === '*' && normPattern[i + 1] === '*') {
+            if (normPattern[i + 2] === '/') {
+                regexStr += '(?:.*\\/)?';
+                i += 3;
+            }
+            else {
+                regexStr += '.*';
+                i += 2;
+            }
+        }
+        else if (c === '*') {
+            regexStr += '[^/]*';
+            i++;
+        }
+        else if (c === '?') {
+            regexStr += '[^/]';
+            i++;
+        }
+        else if (['.', '+', '^', '$', '(', ')', '[', ']', '{', '}', '|'].includes(c)) {
+            regexStr += '\\' + c;
+            i++;
+        }
+        else {
+            regexStr += c;
+            i++;
+        }
+    }
+    regexStr += '$';
+    return new RegExp(regexStr, 'i').test(normStr);
+}
+/**
+ * Normalize a path for platform-accurate comparison.
+ * On Windows, paths are case-insensitive.
+ */
+function normalizeForComparison(p) {
+    const norm = path.normalize(p);
+    return process.platform === 'win32' ? norm.toLowerCase() : norm;
+}
+/**
+ * Check if child is equal to parent or inside parent directory.
+ */
+export function isSubPath(child, parent) {
+    const childNorm = normalizeForComparison(child);
+    const parentNorm = normalizeForComparison(parent);
+    if (childNorm === parentNorm)
+        return true;
+    const rel = path.relative(parentNorm, childNorm);
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+/**
+ * Canonical realpath with Windows long-path prefix stripping.
+ */
+export function getRealPath(p) {
+    let real = fs.realpathSync(p);
+    if (real.startsWith('\\\\?\\')) {
+        real = real.substring(4);
+    }
+    return path.normalize(real);
+}
+export class FileSandbox {
+    config;
+    normalizedRoots = [];
+    defaultRootPath = '';
+    constructor(config) {
+        this.config = config;
+        this.initRoots();
+    }
+    initRoots() {
+        const roots = this.config.allowedRoots.length > 0 ? this.config.allowedRoots : ['./data/workspace'];
+        for (const item of roots) {
+            let rule;
+            if (typeof item === 'string') {
+                rule = { path: item, readOnly: false };
+            }
+            else {
+                rule = item;
+            }
+            const absPath = path.resolve(process.cwd(), rule.path);
+            if (!fs.existsSync(absPath)) {
+                try {
+                    fs.mkdirSync(absPath, { recursive: true });
+                }
+                catch (err) {
+                    logger.warn(`Could not create sandbox root directory ${absPath}: ${err.message}`);
+                }
+            }
+            let canonical = absPath;
+            if (fs.existsSync(absPath)) {
+                try {
+                    canonical = getRealPath(absPath);
+                }
+                catch {
+                    canonical = path.normalize(absPath);
+                }
+            }
+            this.normalizedRoots.push({
+                rawPath: rule.path,
+                resolvedPath: canonical,
+                readOnly: Boolean(rule.readOnly),
+                description: rule.description,
+            });
+        }
+        if (this.config.defaultRoot) {
+            const defaultAbs = path.resolve(process.cwd(), this.config.defaultRoot);
+            this.defaultRootPath = fs.existsSync(defaultAbs) ? getRealPath(defaultAbs) : path.normalize(defaultAbs);
+        }
+        else if (this.normalizedRoots.length > 0) {
+            this.defaultRootPath = this.normalizedRoots[0].resolvedPath;
+        }
+        else {
+            const fallback = path.resolve(process.cwd(), 'data/workspace');
+            if (!fs.existsSync(fallback))
+                fs.mkdirSync(fallback, { recursive: true });
+            this.defaultRootPath = getRealPath(fallback);
+        }
+    }
+    getAllowedRoots() {
+        return [...this.normalizedRoots];
+    }
+    getDefaultRootPath() {
+        return this.defaultRootPath;
+    }
+    /**
+     * Validate path syntax to block malicious tricks:
+     * - Null bytes
+     * - ASCII control characters
+     * - UNC paths
+     * - Windows Alternate Data Streams (colon in segments)
+     * - Windows reserved device names (CON, PRN, AUX, NUL, COM1-9, LPT1-9)
+     */
+    validatePathSyntax(rawPath) {
+        if (typeof rawPath !== 'string' || !rawPath.trim()) {
+            throw new SandboxSecurityError('File path must be a non-empty string.', 'EMPTY_PATH');
+        }
+        // Check for null bytes
+        if (rawPath.includes('\0')) {
+            throw new SandboxSecurityError('Path contains invalid null byte.', 'NULL_BYTE_DETECTED', { path: rawPath });
+        }
+        // Check for ASCII control characters (0x01 - 0x1F)
+        if (/[\x01-\x1F]/.test(rawPath)) {
+            throw new SandboxSecurityError('Path contains illegal control characters.', 'CONTROL_CHAR_DETECTED', { path: rawPath });
+        }
+        // Reject UNC network paths
+        if (rawPath.startsWith('\\\\') || rawPath.startsWith('//')) {
+            throw new SandboxSecurityError('UNC network paths are not permitted in sandbox.', 'UNC_PATH_BLOCKED', { path: rawPath });
+        }
+        // Inspect individual path segments
+        const segments = rawPath.split(/[/\\]+/).filter(Boolean);
+        for (let idx = 0; idx < segments.length; idx++) {
+            const segment = segments[idx];
+            // Check Windows reserved device names
+            if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(\..*)?$/i.test(segment)) {
+                throw new SandboxSecurityError(`Path contains reserved system device name "${segment}".`, 'RESERVED_DEVICE_NAME', { path: rawPath });
+            }
+            // Check for Alternate Data Streams or unexpected colons
+            // Index 0 in Windows absolute paths like "C:" is permitted
+            if (segment.includes(':')) {
+                const isWindowsDrive = idx === 0 && /^[a-zA-Z]:$/.test(segment);
+                if (!isWindowsDrive) {
+                    throw new SandboxSecurityError(`Path contains illegal colon in component "${segment}" (Alternate Data Streams prohibited).`, 'ADS_STREAM_BLOCKED', { path: rawPath });
+                }
+            }
+        }
+    }
+    /**
+     * Validates that a path is fully contained within the allowed sandbox roots,
+     * does not escape via traversal or symlinks, does not match blocked patterns,
+     * and respects permission controls (e.g. readOnly).
+     */
+    validatePath(rawPath, operation) {
+        if (!this.config.enabled) {
+            // If sandboxing is explicitly disabled by config, still prevent null bytes and resolve path
+            this.validatePathSyntax(rawPath);
+            const res = path.isAbsolute(rawPath) ? path.resolve(rawPath) : path.resolve(this.defaultRootPath, rawPath);
+            return {
+                resolvedPath: res,
+                rootRule: {
+                    rawPath: '.',
+                    resolvedPath: process.cwd(),
+                    readOnly: false,
+                },
+            };
+        }
+        // 1. Validate syntax guardrails
+        this.validatePathSyntax(rawPath);
+        // 2. Resolve to absolute path
+        const resolved = path.isAbsolute(rawPath)
+            ? path.resolve(rawPath)
+            : path.resolve(this.defaultRootPath, rawPath);
+        // Guard against accessing system user security directory (~/.musonda)
+        const musondaHome = getMusondaHomeDir();
+        const isTargetingMusonda = isSubPath(resolved, musondaHome) ||
+            (fs.existsSync(musondaHome) && isSubPath(resolved, getRealPath(musondaHome)));
+        if (isTargetingMusonda) {
+            logger.warn(`[SANDBOX_BLOCKED] Attempted access to user security directory "${resolved}".`);
+            throw new SandboxSecurityError(`Access denied: System user security directory "${musondaHome}" is protected by security guardrails.`, 'SECURITY_ROOT_PROTECTED', { path: rawPath });
+        }
+        // 3. Find matching allowed root
+        let matchedRoot;
+        for (const root of this.normalizedRoots) {
+            if (isSubPath(resolved, root.resolvedPath)) {
+                matchedRoot = root;
+                break;
+            }
+        }
+        if (!matchedRoot) {
+            logger.warn(`[SANDBOX_BLOCKED] Path "${rawPath}" resolves to "${resolved}" which is outside allowed sandbox roots.`);
+            throw new SandboxSecurityError(`Access denied: Path "${rawPath}" resolves outside of permitted sandbox directories.`, 'PATH_OUTSIDE_SANDBOX', {
+                path: rawPath,
+                details: {
+                    resolved,
+                    allowedRoots: this.normalizedRoots.map((r) => r.rawPath),
+                },
+            });
+        }
+        // 4. Symlink resolution protection
+        if (fs.existsSync(resolved)) {
+            let realTarget;
+            try {
+                realTarget = getRealPath(resolved);
+            }
+            catch (err) {
+                throw new SandboxSecurityError(`Unable to resolve canonical real path: ${err.message}`, 'REALPATH_RESOLUTION_FAILED', { path: rawPath });
+            }
+            // Verify that canonical real target is inside an allowed root
+            const insideAnyAllowed = this.normalizedRoots.some((r) => isSubPath(realTarget, r.resolvedPath));
+            if (!insideAnyAllowed) {
+                logger.warn(`[SANDBOX_BLOCKED] Symlink escape: "${resolved}" targets "${realTarget}".`);
+                throw new SandboxSecurityError(`Access denied: Target resolves via symbolic link to "${realTarget}", which is outside allowed sandbox roots.`, 'SYMLINK_ESCAPE_DETECTED', { path: rawPath, details: { realTarget } });
+            }
+        }
+        else {
+            // Path does not exist yet (e.g. creating a new file).
+            // Find deepest existing ancestor and ensure its real path does not escape
+            let current = path.dirname(resolved);
+            while (!fs.existsSync(current)) {
+                const parent = path.dirname(current);
+                if (parent === current)
+                    break;
+                current = parent;
+            }
+            if (fs.existsSync(current)) {
+                try {
+                    const realAncestor = getRealPath(current);
+                    const ancestorInside = this.normalizedRoots.some((r) => isSubPath(realAncestor, r.resolvedPath));
+                    if (!ancestorInside) {
+                        logger.warn(`[SANDBOX_BLOCKED] Parent directory resolves to "${realAncestor}" outside sandbox.`);
+                        throw new SandboxSecurityError(`Access denied: Parent directory resolves via symbolic link outside allowed sandbox roots.`, 'SYMLINK_ESCAPE_DETECTED', { path: rawPath });
+                    }
+                }
+                catch (err) {
+                    throw new SandboxSecurityError(`Unable to verify ancestor path: ${err.message}`, 'REALPATH_RESOLUTION_FAILED', { path: rawPath });
+                }
+            }
+        }
+        // 5. Blocked patterns protection
+        const basename = path.basename(resolved);
+        const relativeFromRoot = path.relative(matchedRoot.resolvedPath, resolved).replace(/\\/g, '/');
+        const relativeFromRaw = rawPath.replace(/\\/g, '/');
+        for (const pattern of this.config.blockedPatterns) {
+            if (matchGlob(basename, pattern) ||
+                matchGlob(relativeFromRoot, pattern) ||
+                matchGlob(relativeFromRaw, pattern)) {
+                logger.warn(`[SANDBOX_BLOCKED] Path "${rawPath}" matches restricted pattern "${pattern}".`);
+                throw new SandboxSecurityError(`Access denied: Path "${rawPath}" matches protected file pattern "${pattern}".`, 'RESTRICTED_PATTERN', { path: rawPath, details: { pattern } });
+            }
+        }
+        // 6. Permission & Operation guardrails
+        if (operation === 'write' || operation === 'delete') {
+            if (matchedRoot.readOnly) {
+                throw new SandboxSecurityError(`Access denied: Directory "${matchedRoot.rawPath}" is mounted as read-only. Operation "${operation}" is forbidden.`, 'READ_ONLY_VIOLATION', { path: rawPath, details: { root: matchedRoot.rawPath } });
+            }
+        }
+        if (operation === 'delete') {
+            if (!this.config.allowDelete) {
+                throw new SandboxSecurityError('Access denied: File deletion operations are disabled by policy.', 'DELETE_DISABLED', { path: rawPath });
+            }
+            // Guard against deleting the root sandbox directory itself
+            if (normalizeForComparison(resolved) === normalizeForComparison(matchedRoot.resolvedPath)) {
+                throw new SandboxSecurityError(`Access denied: Cannot delete root sandbox directory "${rawPath}".`, 'ROOT_DELETION_PROHIBITED', { path: rawPath });
+            }
+        }
+        return { resolvedPath: resolved, rootRule: matchedRoot };
+    }
+    // =========================================================================
+    // File Operations (Guarded)
+    // =========================================================================
+    readFile(rawPath, options) {
+        const { resolvedPath } = this.validatePath(rawPath, 'read');
+        if (!fs.existsSync(resolvedPath)) {
+            throw new SandboxSecurityError(`File not found: "${rawPath}".`, 'FILE_NOT_FOUND', { path: rawPath });
+        }
+        const stat = fs.statSync(resolvedPath);
+        if (stat.isDirectory()) {
+            throw new SandboxSecurityError(`Path "${rawPath}" is a directory, not a file. Use file_list to inspect directories.`, 'IS_DIRECTORY', { path: rawPath });
+        }
+        const effectiveMaxBytes = options?.maxBytes
+            ? Math.min(options.maxBytes, this.config.maxReadSizeBytes)
+            : this.config.maxReadSizeBytes;
+        if (stat.size > effectiveMaxBytes && !options?.startLine && !options?.endLine) {
+            throw new SandboxSecurityError(`File size (${stat.size} bytes) exceeds maximum read limit (${effectiveMaxBytes} bytes). Provide startLine and endLine to paginate through this file.`, 'FILE_TOO_LARGE', { path: rawPath, details: { size: stat.size, maxAllowed: effectiveMaxBytes } });
+        }
+        const encoding = options?.encoding || 'utf-8';
+        if (encoding === 'base64') {
+            const buffer = fs.readFileSync(resolvedPath);
+            return {
+                path: rawPath,
+                content: buffer.toString('base64'),
+                totalBytes: stat.size,
+            };
+        }
+        const fullContent = fs.readFileSync(resolvedPath, 'utf-8');
+        if (options?.startLine !== undefined || options?.endLine !== undefined) {
+            const lines = fullContent.split(/\r?\n/);
+            const totalLines = lines.length;
+            const start = Math.max(1, options.startLine || 1);
+            const end = options.endLine ? Math.min(totalLines, options.endLine) : totalLines;
+            if (start > totalLines) {
+                return {
+                    path: rawPath,
+                    content: '',
+                    startLine: start,
+                    endLine: end,
+                    totalLines,
+                    totalBytes: stat.size,
+                };
+            }
+            const slicedLines = lines.slice(start - 1, end);
+            return {
+                path: rawPath,
+                content: slicedLines.join('\n'),
+                startLine: start,
+                endLine: end,
+                totalLines,
+                totalBytes: stat.size,
+                truncated: start > 1 || end < totalLines,
+            };
+        }
+        return {
+            path: rawPath,
+            content: fullContent,
+            totalBytes: stat.size,
+        };
+    }
+    writeFile(rawPath, content, options) {
+        const { resolvedPath } = this.validatePath(rawPath, 'write');
+        const encoding = options?.encoding || 'utf-8';
+        const buffer = Buffer.from(content, encoding);
+        if (buffer.length > this.config.maxWriteSizeBytes) {
+            throw new SandboxSecurityError(`Content size (${buffer.length} bytes) exceeds maximum write limit (${this.config.maxWriteSizeBytes} bytes).`, 'CONTENT_TOO_LARGE', { path: rawPath, details: { size: buffer.length, maxAllowed: this.config.maxWriteSizeBytes } });
+        }
+        if (fs.existsSync(resolvedPath)) {
+            if (options?.overwrite === false) {
+                throw new SandboxSecurityError(`File "${rawPath}" already exists and overwrite is set to false.`, 'FILE_EXISTS', { path: rawPath });
+            }
+            const stat = fs.statSync(resolvedPath);
+            if (stat.isDirectory()) {
+                throw new SandboxSecurityError(`Cannot write to "${rawPath}" because it is an existing directory.`, 'IS_DIRECTORY', { path: rawPath });
+            }
+        }
+        const parentDir = path.dirname(resolvedPath);
+        if (!fs.existsSync(parentDir)) {
+            fs.mkdirSync(parentDir, { recursive: true });
+        }
+        fs.writeFileSync(resolvedPath, buffer);
+        logger.info(`[FILE_SANDBOX] Wrote ${buffer.length} bytes to "${rawPath}"`);
+        return {
+            success: true,
+            path: rawPath,
+            bytesWritten: buffer.length,
+        };
+    }
+    editFile(rawPath, target, replacement, allowMultiple = false) {
+        const { resolvedPath } = this.validatePath(rawPath, 'write');
+        if (!fs.existsSync(resolvedPath)) {
+            throw new SandboxSecurityError(`File not found for edit: "${rawPath}".`, 'FILE_NOT_FOUND', { path: rawPath });
+        }
+        const stat = fs.statSync(resolvedPath);
+        if (stat.isDirectory()) {
+            throw new SandboxSecurityError(`Cannot edit "${rawPath}" because it is a directory.`, 'IS_DIRECTORY', { path: rawPath });
+        }
+        const content = fs.readFileSync(resolvedPath, 'utf-8');
+        if (!target) {
+            throw new SandboxSecurityError('Target string to replace cannot be empty.', 'EMPTY_TARGET');
+        }
+        // Count occurrences
+        let count = 0;
+        let pos = 0;
+        while ((pos = content.indexOf(target, pos)) !== -1) {
+            count++;
+            pos += target.length;
+        }
+        if (count === 0) {
+            throw new SandboxSecurityError(`Target text snippet was not found in file "${rawPath}". Please check the text and try again.`, 'TARGET_NOT_FOUND', { path: rawPath });
+        }
+        if (count > 1 && !allowMultiple) {
+            throw new SandboxSecurityError(`Target snippet was found ${count} times in "${rawPath}". Provide more surrounding lines to uniquely identify the section, or set allowMultiple: true.`, 'AMBIGUOUS_TARGET', { path: rawPath, details: { occurrences: count } });
+        }
+        let newContent;
+        if (allowMultiple) {
+            newContent = content.split(target).join(replacement);
+        }
+        else {
+            newContent = content.replace(target, replacement);
+        }
+        const buffer = Buffer.from(newContent, 'utf-8');
+        if (buffer.length > this.config.maxWriteSizeBytes) {
+            throw new SandboxSecurityError(`Edited file size (${buffer.length} bytes) exceeds maximum write limit (${this.config.maxWriteSizeBytes} bytes).`, 'CONTENT_TOO_LARGE', { path: rawPath });
+        }
+        fs.writeFileSync(resolvedPath, buffer);
+        logger.info(`[FILE_SANDBOX] Edited "${rawPath}": replaced ${count} occurrence(s)`);
+        return {
+            success: true,
+            path: rawPath,
+            occurrencesReplaced: count,
+            bytesWritten: buffer.length,
+        };
+    }
+    appendFile(rawPath, content) {
+        const { resolvedPath } = this.validatePath(rawPath, 'write');
+        const buffer = Buffer.from(content, 'utf-8');
+        const existingSize = fs.existsSync(resolvedPath) ? fs.statSync(resolvedPath).size : 0;
+        if (existingSize + buffer.length > this.config.maxWriteSizeBytes) {
+            throw new SandboxSecurityError(`Resulting file size (${existingSize + buffer.length} bytes) exceeds maximum write limit (${this.config.maxWriteSizeBytes} bytes).`, 'CONTENT_TOO_LARGE', { path: rawPath });
+        }
+        const parentDir = path.dirname(resolvedPath);
+        if (!fs.existsSync(parentDir)) {
+            fs.mkdirSync(parentDir, { recursive: true });
+        }
+        fs.appendFileSync(resolvedPath, buffer);
+        logger.info(`[FILE_SANDBOX] Appended ${buffer.length} bytes to "${rawPath}"`);
+        return {
+            success: true,
+            path: rawPath,
+            bytesAppended: buffer.length,
+        };
+    }
+    listFiles(rawPath = '.', options) {
+        const { resolvedPath, rootRule } = this.validatePath(rawPath, 'read');
+        if (!fs.existsSync(resolvedPath)) {
+            throw new SandboxSecurityError(`Directory not found: "${rawPath}".`, 'DIRECTORY_NOT_FOUND', { path: rawPath });
+        }
+        const stat = fs.statSync(resolvedPath);
+        if (!stat.isDirectory()) {
+            throw new SandboxSecurityError(`Path "${rawPath}" is a file, not a directory.`, 'NOT_A_DIRECTORY', { path: rawPath });
+        }
+        const entries = [];
+        const maxEntries = this.config.maxListEntries;
+        let truncated = false;
+        const recursive = Boolean(options?.recursive);
+        const maxDepth = options?.maxDepth !== undefined ? options.maxDepth : 2;
+        const traverse = (currentDir, depth) => {
+            if (entries.length >= maxEntries) {
+                truncated = true;
+                return;
+            }
+            let dirents;
+            try {
+                dirents = fs.readdirSync(currentDir, { withFileTypes: true });
+            }
+            catch (err) {
+                logger.warn(`Could not read directory ${currentDir}: ${err.message}`);
+                return;
+            }
+            for (const dirent of dirents) {
+                if (entries.length >= maxEntries) {
+                    truncated = true;
+                    return;
+                }
+                const fullPath = path.join(currentDir, dirent.name);
+                const relFromTarget = path.relative(resolvedPath, fullPath).replace(/\\/g, '/');
+                const relFromRoot = path.relative(rootRule.resolvedPath, fullPath).replace(/\\/g, '/');
+                // Check if item matches blocked patterns
+                const isBlocked = this.config.blockedPatterns.some((p) => matchGlob(dirent.name, p) || matchGlob(relFromRoot, p));
+                if (isBlocked) {
+                    continue;
+                }
+                let isDir = dirent.isDirectory();
+                let isFile = dirent.isFile();
+                let size = 0;
+                let modifiedAt = '';
+                try {
+                    const s = fs.statSync(fullPath);
+                    size = s.size;
+                    modifiedAt = s.mtime.toISOString();
+                    isDir = s.isDirectory();
+                    isFile = s.isFile();
+                }
+                catch {
+                    // In case of broken link or permission
+                }
+                entries.push({
+                    name: dirent.name,
+                    relativePath: relFromTarget,
+                    isDirectory: isDir,
+                    isFile: isFile,
+                    sizeBytes: size,
+                    modifiedAt,
+                });
+                if (isDir && recursive && depth < maxDepth) {
+                    traverse(fullPath, depth + 1);
+                }
+            }
+        };
+        traverse(resolvedPath, 1);
+        return {
+            directory: rawPath,
+            totalEntries: entries.length,
+            truncated,
+            entries,
+        };
+    }
+    deletePath(rawPath, recursive = false) {
+        const { resolvedPath, rootRule } = this.validatePath(rawPath, 'delete');
+        if (!fs.existsSync(resolvedPath)) {
+            throw new SandboxSecurityError(`Path not found for deletion: "${rawPath}".`, 'FILE_NOT_FOUND', { path: rawPath });
+        }
+        const stat = fs.statSync(resolvedPath);
+        if (stat.isDirectory()) {
+            const children = fs.readdirSync(resolvedPath);
+            if (children.length > 0 && !recursive) {
+                throw new SandboxSecurityError(`Directory "${rawPath}" is not empty. Set recursive: true to delete non-empty directories.`, 'DIRECTORY_NOT_EMPTY', { path: rawPath, details: { itemCount: children.length } });
+            }
+            // Verify no blocked files exist inside before recursive deletion
+            if (recursive) {
+                this.verifyNoBlockedFilesInTree(resolvedPath, rootRule.resolvedPath);
+            }
+            fs.rmSync(resolvedPath, { recursive: true, force: true });
+        }
+        else {
+            fs.unlinkSync(resolvedPath);
+        }
+        logger.info(`[FILE_SANDBOX] Deleted "${rawPath}" (recursive: ${recursive})`);
+        return {
+            success: true,
+            path: rawPath,
+            deleted: true,
+        };
+    }
+    verifyNoBlockedFilesInTree(dir, rootCanonical) {
+        const dirents = fs.readdirSync(dir, { withFileTypes: true });
+        for (const d of dirents) {
+            const full = path.join(dir, d.name);
+            const rel = path.relative(rootCanonical, full).replace(/\\/g, '/');
+            for (const pattern of this.config.blockedPatterns) {
+                if (matchGlob(d.name, pattern) || matchGlob(rel, pattern)) {
+                    throw new SandboxSecurityError(`Cannot recursively delete directory containing protected file "${d.name}" (pattern "${pattern}").`, 'PROTECTED_FILE_IN_TREE', { path: full, details: { pattern } });
+                }
+            }
+            if (d.isDirectory()) {
+                this.verifyNoBlockedFilesInTree(full, rootCanonical);
+            }
+        }
+    }
+    getFileInfo(rawPath) {
+        const { resolvedPath, rootRule } = this.validatePath(rawPath, 'read');
+        if (!fs.existsSync(resolvedPath)) {
+            return {
+                exists: false,
+                path: rawPath,
+            };
+        }
+        const stat = fs.statSync(resolvedPath);
+        return {
+            exists: true,
+            path: rawPath,
+            isFile: stat.isFile(),
+            isDirectory: stat.isDirectory(),
+            isSymbolicLink: stat.isSymbolicLink(),
+            sizeBytes: stat.size,
+            createdAt: stat.birthtime.toISOString(),
+            modifiedAt: stat.mtime.toISOString(),
+            readOnly: rootRule.readOnly,
+        };
+    }
+    createDirectory(rawPath) {
+        const { resolvedPath } = this.validatePath(rawPath, 'write');
+        if (fs.existsSync(resolvedPath)) {
+            const stat = fs.statSync(resolvedPath);
+            if (stat.isDirectory()) {
+                return { success: true, path: rawPath, created: false };
+            }
+            throw new SandboxSecurityError(`Path "${rawPath}" already exists and is a file.`, 'PATH_EXISTS_AS_FILE', { path: rawPath });
+        }
+        fs.mkdirSync(resolvedPath, { recursive: true });
+        logger.info(`[FILE_SANDBOX] Created directory "${rawPath}"`);
+        return {
+            success: true,
+            path: rawPath,
+            created: true,
+        };
+    }
+    searchFiles(pattern, rawPath = '.', maxResults = 50) {
+        const { resolvedPath, rootRule } = this.validatePath(rawPath, 'read');
+        if (!fs.existsSync(resolvedPath)) {
+            throw new SandboxSecurityError(`Search path not found: "${rawPath}".`, 'DIRECTORY_NOT_FOUND', { path: rawPath });
+        }
+        const matches = [];
+        const limit = Math.min(maxResults, this.config.maxListEntries);
+        let truncated = false;
+        const traverse = (currentDir, depth) => {
+            if (matches.length >= limit || depth > 10) {
+                if (matches.length >= limit)
+                    truncated = true;
+                return;
+            }
+            let dirents;
+            try {
+                dirents = fs.readdirSync(currentDir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const d of dirents) {
+                if (matches.length >= limit) {
+                    truncated = true;
+                    return;
+                }
+                const fullPath = path.join(currentDir, d.name);
+                const relFromRoot = path.relative(rootRule.resolvedPath, fullPath).replace(/\\/g, '/');
+                const relFromSearch = path.relative(resolvedPath, fullPath).replace(/\\/g, '/');
+                // Check blocked patterns
+                const isBlocked = this.config.blockedPatterns.some((p) => matchGlob(d.name, p) || matchGlob(relFromRoot, p));
+                if (isBlocked)
+                    continue;
+                // Check match
+                if (matchGlob(d.name, pattern) || d.name.toLowerCase().includes(pattern.toLowerCase())) {
+                    let size = 0;
+                    try {
+                        size = fs.statSync(fullPath).size;
+                    }
+                    catch { }
+                    matches.push({
+                        name: d.name,
+                        relativePath: relFromSearch,
+                        isDirectory: d.isDirectory(),
+                        sizeBytes: size,
+                    });
+                }
+                if (d.isDirectory()) {
+                    traverse(fullPath, depth + 1);
+                }
+            }
+        };
+        traverse(resolvedPath, 1);
+        return {
+            pattern,
+            totalMatches: matches.length,
+            truncated,
+            matches,
+        };
+    }
+    grepFiles(query, rawPath = '.', options) {
+        const { resolvedPath, rootRule } = this.validatePath(rawPath, 'read');
+        if (!fs.existsSync(resolvedPath)) {
+            throw new SandboxSecurityError(`Path not found: "${rawPath}".`, 'FILE_NOT_FOUND', { path: rawPath });
+        }
+        const matches = [];
+        const limit = Math.min(options?.maxResults || 50, this.config.maxListEntries);
+        const caseInsensitive = options?.caseInsensitive ?? true;
+        const lowerQuery = query.toLowerCase();
+        let truncated = false;
+        const searchFile = (filePath) => {
+            if (matches.length >= limit) {
+                truncated = true;
+                return;
+            }
+            let content;
+            try {
+                const stat = fs.statSync(filePath);
+                if (stat.size > this.config.maxReadSizeBytes)
+                    return; // Skip oversized files
+                // Check for binary file by reading first 512 bytes
+                const fd = fs.openSync(filePath, 'r');
+                const buf = Buffer.alloc(512);
+                const bytesRead = fs.readSync(fd, buf, 0, 512, 0);
+                fs.closeSync(fd);
+                for (let i = 0; i < bytesRead; i++) {
+                    if (buf[i] === 0)
+                        return; // Binary file, skip
+                }
+                content = fs.readFileSync(filePath, 'utf-8');
+            }
+            catch {
+                return;
+            }
+            const lines = content.split(/\r?\n/);
+            const relFromSearch = path.relative(resolvedPath, filePath).replace(/\\/g, '/');
+            for (let i = 0; i < lines.length; i++) {
+                if (matches.length >= limit) {
+                    truncated = true;
+                    return;
+                }
+                const line = lines[i];
+                const hasMatch = caseInsensitive
+                    ? line.toLowerCase().includes(lowerQuery)
+                    : line.includes(query);
+                if (hasMatch) {
+                    matches.push({
+                        file: relFromSearch,
+                        line: i + 1,
+                        text: line.trimEnd(),
+                    });
+                }
+            }
+        };
+        const traverse = (dir) => {
+            if (matches.length >= limit) {
+                truncated = true;
+                return;
+            }
+            let dirents;
+            try {
+                dirents = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const d of dirents) {
+                if (matches.length >= limit) {
+                    truncated = true;
+                    return;
+                }
+                const fullPath = path.join(dir, d.name);
+                const relFromRoot = path.relative(rootRule.resolvedPath, fullPath).replace(/\\/g, '/');
+                const isBlocked = this.config.blockedPatterns.some((p) => matchGlob(d.name, p) || matchGlob(relFromRoot, p));
+                if (isBlocked)
+                    continue;
+                if (d.isDirectory()) {
+                    traverse(fullPath);
+                }
+                else if (d.isFile()) {
+                    searchFile(fullPath);
+                }
+            }
+        };
+        const stat = fs.statSync(resolvedPath);
+        if (stat.isFile()) {
+            searchFile(resolvedPath);
+        }
+        else {
+            traverse(resolvedPath);
+        }
+        return {
+            query,
+            totalMatches: matches.length,
+            truncated,
+            matches,
+        };
+    }
+}
+//# sourceMappingURL=fileSandbox.js.map