/**
 * Path Validation Utilities
 *
 * Security-focused path validation to prevent path traversal attacks
 * and ensure paths are within allowed boundaries.
 *
 * @module util/paths
 */
/**
 * Error thrown when path validation fails
 */
export declare class PathValidationError extends Error {
    readonly path: string;
    readonly reason: "not_found" | "not_directory" | "symlink_escape" | "path_traversal" | "invalid_path";
    constructor(message: string, path: string, reason: "not_found" | "not_directory" | "symlink_escape" | "path_traversal" | "invalid_path");
}
export interface ValidatePathOptions {
    /** Require the path to be a directory (default: true) */
    requireDirectory?: boolean;
    /** Allow symlinks (default: false - symlinks are resolved and checked) */
    allowSymlinks?: boolean;
    /** Base directory that the path must be within (optional) */
    basePath?: string;
}
/**
 * Validate a project path for security
 *
 * Checks:
 * 1. Path is absolute after resolution
 * 2. Path exists on the filesystem
 * 3. Path is a directory (optional)
 * 4. Symlinks are resolved and checked (optional)
 * 5. Path doesn't escape base directory (optional)
 *
 * @param projectPath - The path to validate
 * @param options - Validation options
 * @returns The validated, resolved absolute path
 * @throws PathValidationError if validation fails
 */
export declare function validateProjectPath(projectPath: string, options?: ValidatePathOptions): Promise<string>;
/**
 * Validate a file path (not requiring directory)
 */
export declare function validateFilePath(filePath: string, options?: Omit<ValidatePathOptions, "requireDirectory">): Promise<string>;
/**
 * Check if a path is safe (doesn't throw, returns boolean)
 */
export declare function isPathSafe(projectPath: string, options?: ValidatePathOptions): Promise<boolean>;
/**
 * Resolve a relative file path inside a project tree, rejecting escapes.
 * For paths that originate from untrusted sources (scanner output, agent
 * findings): `../` sequences, absolute paths, and in-tree symlinks
 * pointing outside the project are all refused.
 *
 * @returns The real (symlink-resolved) absolute path of the file
 * @throws PathValidationError if the path escapes the project tree
 */
export declare function resolveContainedFile(projectPath: string, relFile: string): Promise<string>;
/**
 * Resolve a relative *write* target inside a project tree, rejecting
 * escapes — like resolveContainedFile but for a file that may not exist
 * yet (the parent directory must exist and is symlink-resolved).
 * For untrusted output paths (e.g. an `output_file` tool argument).
 *
 * @returns The absolute path to write to, contained within the tree
 * @throws PathValidationError if the path escapes the project tree
 */
export declare function resolveContainedWritePath(projectPath: string, relFile: string): Promise<string>;
/**
 * Sanitize a path for use in error messages (remove sensitive info)
 */
export declare function sanitizePathForLogging(inputPath: string): string;
//# sourceMappingURL=paths.d.ts.map