@phuetz/code-buddy 0.1.0

package/dist/utils/input-validation/index.d.ts

@@ -0,0 +1,469 @@
+/**
+ * Input Validation Module
+ *
+ * Barrel re-exports plus remaining validators (tool schemas,
+ * URL sanitization, unified validators object, bash tool schemas).
+ */
+import { z, ZodSchema } from 'zod';
+export type { ValidationResult, ValidationOptions } from './types.js';
+export { VALIDATION_LIMITS } from './constants.js';
+export { validateString, validateStringLength, validatePattern, validateNumber, validateNumberRange, validatePositiveInteger, validateArray, validateObject, validateChoice, validateBoolean, validateUrl, validateEmail, validateOptional, validateWithDefault, type SchemaField, type Schema, validateSchema, assertValid, createAssertingValidator, assertString, assertNumber, assertPositiveInteger, assertArray, assertObject, assertBoolean, assertUrl, assertEmail, } from './common-validators.js';
+export { validateFilePath, sanitizeFilePath, isPathSafeForWrite, type PathValidationOptions, type UnifiedValidationResult, validatePath, DANGEROUS_PATH_PATTERNS, } from './path-validator.js';
+export { validateCommand, sanitizeForShell, } from './command-validator.js';
+import type { ValidationResult } from './types.js';
+import type { UnifiedValidationResult } from './path-validator.js';
+import { validatePath } from './path-validator.js';
+export declare const assertFilePath: (value: unknown, context?: string, options?: import("./types.js").ValidationOptions) => string;
+/**
+ * Schemas for bash tool operations
+ */
+export declare const bashToolSchemas: {
+    execute: {
+        command: {
+            type: "string";
+            required: boolean;
+            minLength: number;
+        };
+        timeout: {
+            type: "number";
+            required: boolean;
+            min: number;
+            max: number;
+        };
+    };
+    listFiles: {
+        directory: {
+            type: "string";
+            required: boolean;
+        };
+    };
+    findFiles: {
+        pattern: {
+            type: "string";
+            required: boolean;
+            minLength: number;
+        };
+        directory: {
+            type: "string";
+            required: boolean;
+        };
+    };
+    grep: {
+        pattern: {
+            type: "string";
+            required: boolean;
+            minLength: number;
+        };
+        files: {
+            type: "string";
+            required: boolean;
+        };
+    };
+};
+/**
+ * Validate input against a schema
+ */
+export declare function validateWithSchema(schema: Record<string, {
+    type: string;
+    required?: boolean;
+    minLength?: number;
+    min?: number;
+    max?: number;
+}>, input: Record<string, unknown>, _context: string): ValidationResult<Record<string, unknown>>;
+/**
+ * Schema for view_file tool
+ */
+export declare const viewFileSchema: z.ZodEffects<z.ZodObject<{
+    path: z.ZodEffects<z.ZodString, string, string>;
+    start_line: z.ZodOptional<z.ZodNumber>;
+    end_line: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    start_line?: number | undefined;
+    end_line?: number | undefined;
+}, {
+    path: string;
+    start_line?: number | undefined;
+    end_line?: number | undefined;
+}>, {
+    path: string;
+    start_line?: number | undefined;
+    end_line?: number | undefined;
+}, {
+    path: string;
+    start_line?: number | undefined;
+    end_line?: number | undefined;
+}>;
+/**
+ * Schema for create_file tool
+ */
+export declare const createFileSchema: z.ZodObject<{
+    path: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    path: string;
+}, {
+    content: string;
+    path: string;
+}>;
+/**
+ * Schema for str_replace_editor tool
+ */
+export declare const strReplaceEditorSchema: z.ZodObject<{
+    path: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
+    old_str: z.ZodString;
+    new_str: z.ZodString;
+    replace_all: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    old_str: string;
+    new_str: string;
+    replace_all?: boolean | undefined;
+}, {
+    path: string;
+    old_str: string;
+    new_str: string;
+    replace_all?: boolean | undefined;
+}>;
+/**
+ * Schema for edit_file (Morph) tool
+ */
+export declare const editFileSchema: z.ZodObject<{
+    target_file: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>, string, string>;
+    instructions: z.ZodString;
+    code_edit: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    target_file: string;
+    instructions: string;
+    code_edit: string;
+}, {
+    target_file: string;
+    instructions: string;
+    code_edit: string;
+}>;
+/**
+ * Schema for bash tool
+ */
+export declare const bashSchema: z.ZodObject<{
+    command: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    command: string;
+}, {
+    command: string;
+}>;
+/**
+ * Schema for search tool
+ */
+export declare const searchSchema: z.ZodObject<{
+    query: z.ZodString;
+    include_pattern: z.ZodOptional<z.ZodString>;
+    exclude_pattern: z.ZodOptional<z.ZodString>;
+    case_sensitive: z.ZodOptional<z.ZodBoolean>;
+    regex: z.ZodOptional<z.ZodBoolean>;
+    max_results: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    regex?: boolean | undefined;
+    include_pattern?: string | undefined;
+    exclude_pattern?: string | undefined;
+    case_sensitive?: boolean | undefined;
+    max_results?: number | undefined;
+}, {
+    query: string;
+    regex?: boolean | undefined;
+    include_pattern?: string | undefined;
+    exclude_pattern?: string | undefined;
+    case_sensitive?: boolean | undefined;
+    max_results?: number | undefined;
+}>;
+/**
+ * Schema for web_search tool
+ */
+export declare const webSearchSchema: z.ZodObject<{
+    query: z.ZodString;
+    max_results: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    max_results?: number | undefined;
+}, {
+    query: string;
+    max_results?: number | undefined;
+}>;
+/**
+ * Schema for web_fetch tool
+ */
+export declare const webFetchSchema: z.ZodObject<{
+    url: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+}, {
+    url: string;
+}>;
+/**
+ * Schema for create_todo_list tool
+ */
+export declare const createTodoListSchema: z.ZodObject<{
+    todos: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        content: z.ZodString;
+        status: z.ZodEnum<["pending", "in_progress", "completed", "blocked"]>;
+        priority: z.ZodDefault<z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        status: "pending" | "completed" | "in_progress" | "blocked";
+        content: string;
+        priority: "low" | "medium" | "high";
+    }, {
+        id: string;
+        status: "pending" | "completed" | "in_progress" | "blocked";
+        content: string;
+        priority?: "low" | "medium" | "high" | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    todos: {
+        id: string;
+        status: "pending" | "completed" | "in_progress" | "blocked";
+        content: string;
+        priority: "low" | "medium" | "high";
+    }[];
+}, {
+    todos: {
+        id: string;
+        status: "pending" | "completed" | "in_progress" | "blocked";
+        content: string;
+        priority?: "low" | "medium" | "high" | undefined;
+    }[];
+}>;
+/**
+ * Schema for update_todo_list tool
+ */
+export declare const updateTodoListSchema: z.ZodObject<{
+    updates: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodOptional<z.ZodEnum<["pending", "in_progress", "completed", "blocked"]>>;
+        content: z.ZodOptional<z.ZodString>;
+        priority: z.ZodOptional<z.ZodEnum<["low", "medium", "high"]>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        status?: "pending" | "completed" | "in_progress" | "blocked" | undefined;
+        content?: string | undefined;
+        priority?: "low" | "medium" | "high" | undefined;
+    }, {
+        id: string;
+        status?: "pending" | "completed" | "in_progress" | "blocked" | undefined;
+        content?: string | undefined;
+        priority?: "low" | "medium" | "high" | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    updates: {
+        id: string;
+        status?: "pending" | "completed" | "in_progress" | "blocked" | undefined;
+        content?: string | undefined;
+        priority?: "low" | "medium" | "high" | undefined;
+    }[];
+}, {
+    updates: {
+        id: string;
+        status?: "pending" | "completed" | "in_progress" | "blocked" | undefined;
+        content?: string | undefined;
+        priority?: "low" | "medium" | "high" | undefined;
+    }[];
+}>;
+/**
+ * Registry mapping tool names to their validation schemas
+ */
+export declare const TOOL_SCHEMAS: Record<string, ZodSchema>;
+/**
+ * Validation error with structured details
+ */
+export declare class ToolValidationError extends Error {
+    readonly toolName: string;
+    readonly issues: Array<{
+        path: string;
+        message: string;
+    }>;
+    constructor(toolName: string, issues: Array<{
+        path: string;
+        message: string;
+    }>);
+}
+/**
+ * Validate tool arguments using the appropriate schema
+ *
+ * @param toolName - Name of the tool being called
+ * @param args - Arguments to validate
+ * @returns Validated and transformed arguments
+ * @throws ToolValidationError if validation fails
+ */
+export declare function validateToolArgs<T = Record<string, unknown>>(toolName: string, args: unknown): T;
+/**
+ * Safe validation that returns a result object instead of throwing
+ */
+export declare function safeValidateToolArgs<T = Record<string, unknown>>(toolName: string, args: unknown): ValidationResult<T>;
+/**
+ * Sanitize and validate a URL for fetching
+ *
+ * @param url - The URL to sanitize
+ * @returns The validated URL
+ * @throws Error if URL is invalid or blocked
+ */
+export declare function sanitizeUrl(url: string): string;
+/**
+ * Check if a URL is safe for fetching (doesn't throw, returns boolean)
+ */
+export declare function isUrlSafe(url: string): boolean;
+/**
+ * Options for URL validation in unified validators
+ */
+export interface UrlValidationOptions {
+    /** Allowed protocols (default: ['http:', 'https:']) */
+    protocols?: string[];
+    /** Block internal/localhost URLs (default: true) */
+    blockInternal?: boolean;
+    /** Field name for error messages */
+    fieldName?: string;
+}
+/**
+ * Options for JSON parsing in unified validators
+ */
+export interface JsonParseOptions {
+    /** Maximum JSON string length */
+    maxLength?: number;
+    /** Custom error message prefix */
+    errorPrefix?: string;
+}
+/**
+ * Options for string sanitization
+ */
+export interface SanitizeOptions {
+    /** Remove control characters (default: true) */
+    removeControlChars?: boolean;
+    /** Escape HTML entities (default: false) */
+    escapeHtml?: boolean;
+    /** Maximum length (truncate if exceeded) */
+    maxLength?: number;
+    /** Trim whitespace (default: true) */
+    trim?: boolean;
+}
+/**
+ * Unified validators object providing a consistent API for all validation needs.
+ *
+ * All validators return a UnifiedValidationResult with:
+ * - valid: boolean indicating success
+ * - value: the validated/sanitized value (if valid)
+ * - error: descriptive error message (if invalid)
+ *
+ * @example
+ * ```typescript
+ * const pathResult = validators.path('/some/file.ts');
+ * if (pathResult.valid) {
+ *   console.log('Safe path:', pathResult.value);
+ * }
+ *
+ * const urlResult = validators.url('https://example.com');
+ * if (!urlResult.valid) {
+ *   console.error('Invalid URL:', urlResult.error);
+ * }
+ * ```
+ */
+export declare const validators: {
+    /**
+     * Validate a file path for security and correctness.
+     *
+     * Checks for:
+     * - Path traversal attacks (../)
+     * - Null byte injection
+     * - Dangerous paths (sensitive system files)
+     * - Absolute/relative path restrictions
+     *
+     * @param input - The path to validate
+     * @param options - Validation options
+     * @returns ValidationResult with sanitized path or error
+     */
+    path: typeof validatePath;
+    /**
+     * Validate a URL for security and correctness.
+     *
+     * Checks for:
+     * - Valid URL format
+     * - Allowed protocols (http/https by default)
+     * - Internal/localhost blocking
+     * - JavaScript protocol (XSS prevention)
+     *
+     * @param input - The URL to validate
+     * @param options - Validation options
+     * @returns ValidationResult with URL string or error
+     */
+    url: (input: string, options?: UrlValidationOptions) => UnifiedValidationResult<string>;
+    /**
+     * Parse and validate a JSON string.
+     *
+     * Features:
+     * - Safe JSON parsing with error handling
+     * - Size limits to prevent DoS
+     * - Clear error messages for parse failures
+     *
+     * @param input - The JSON string to parse
+     * @param options - Parse options
+     * @returns Parsed value or null on failure
+     */
+    json: <T = unknown>(input: string, options?: JsonParseOptions) => T | null;
+    /**
+     * Parse JSON with detailed error information.
+     * Use this when you need to know why parsing failed.
+     *
+     * @param input - The JSON string to parse
+     * @param options - Parse options
+     * @returns ValidationResult with parsed value or error
+     */
+    jsonWithError: <T = unknown>(input: string, options?: JsonParseOptions) => UnifiedValidationResult<T>;
+    /**
+     * Sanitize a string by removing dangerous content.
+     *
+     * Features:
+     * - Removes control characters
+     * - Optionally escapes HTML entities
+     * - Enforces length limits
+     * - Trims whitespace
+     *
+     * @param input - The string to sanitize
+     * @param options - Sanitization options
+     * @returns Sanitized string
+     */
+    sanitize: (input: string, options?: SanitizeOptions) => string;
+    /**
+     * Escape a string for safe use in shell commands.
+     * Wraps the string in single quotes and escapes internal quotes.
+     *
+     * @param input - The string to escape
+     * @returns Shell-safe escaped string
+     */
+    shellEscape: (input: string) => string;
+    /**
+     * Validate a command for dangerous patterns.
+     *
+     * Checks for:
+     * - Dangerous commands (rm -rf, fork bombs, etc.)
+     * - Command injection patterns
+     * - Remote code execution attempts
+     *
+     * @param input - The command to validate
+     * @returns ValidationResult with command or error
+     */
+    command: (input: string) => UnifiedValidationResult<string>;
+    /**
+     * Check if a file path is safe (simple boolean check).
+     * Use validators.path() for detailed validation with options.
+     */
+    isPathSafe: (input: string) => boolean;
+    /**
+     * Check if a URL is safe (simple boolean check).
+     * Use validators.url() for detailed validation with options.
+     */
+    isUrlSafe: (input: string) => boolean;
+    /**
+     * Check if a string is valid JSON (simple boolean check).
+     */
+    isValidJson: (input: string) => boolean;
+};