@cyanheads/git-mcp-server/dist/utils/security/sanitization.d.ts

An MCP (Model Context Protocol) server enabling LLMs and AI agents to interact with Git repositories. Provides tools for comprehensive Git operations including clone, commit, branch, diff, log, status, push, pull, merge, rebase, worktree, tag management,

import sanitizeHtml from "sanitize-html";
/**
 * Options for path sanitization.
 */
export interface PathSanitizeOptions {
    /**
     * Restrict paths to a specific root directory.
     * If provided, the sanitized path will be relative to this root,
     * and attempts to traverse above this root will be prevented.
     */
    rootDir?: string;
    /**
     * Normalize Windows-style backslashes (`\\`) to POSIX-style forward slashes (`/`).
     * Defaults to `false`.
     */
    toPosix?: boolean;
    /**
     * Allow absolute paths.
     * If `false` (default), absolute paths will be converted to relative paths
     * (by removing leading slashes or drive letters).
     * If `true`, absolute paths are permitted, subject to `rootDir` constraints if provided.
     */
    allowAbsolute?: boolean;
}
/**
 * Information returned by the sanitizePath method, providing details about the sanitization process.
 */
export interface SanitizedPathInfo {
    /** The final sanitized and normalized path string. */
    sanitizedPath: string;
    /** The original path string passed to the function before any normalization or sanitization. */
    originalInput: string;
    /** Indicates if the input path was determined to be absolute after initial `path.normalize()`. */
    wasAbsolute: boolean;
    /**
     * Indicates if an initially absolute path was converted to a relative path.
     * This typically happens if `options.allowAbsolute` was `false`.
     */
    convertedToRelative: boolean;
    /** The effective options that were used for sanitization, including defaults. */
    optionsUsed: PathSanitizeOptions;
}
/**
 * Context-specific input sanitization options
 */
export interface SanitizeStringOptions {
    /** Handle content differently based on context */
    context?: "text" | "html" | "attribute" | "url" | "javascript";
    /** Custom allowed tags when using html context */
    allowedTags?: string[];
    /** Custom allowed attributes when using html context */
    allowedAttributes?: Record<string, string[]>;
}
/**
 * Configuration for HTML sanitization
 */
export interface HtmlSanitizeConfig {
    /** Allowed HTML tags */
    allowedTags?: string[];
    /** Allowed HTML attributes (global or per-tag) */
    allowedAttributes?: sanitizeHtml.IOptions["allowedAttributes"];
    /** Allow preserving comments - uses allowedTags internally */
    preserveComments?: boolean;
    /** Custom URL sanitizer */
    transformTags?: sanitizeHtml.IOptions["transformTags"];
}
/**
 * Sanitization class for handling various input sanitization tasks.
 * Provides methods to clean and validate strings, HTML, URLs, paths, JSON, and numbers.
 */
export declare class Sanitization {
    private static instance;
    /** Default list of sensitive fields for sanitizing logs */
    private sensitiveFields;
    /** Default sanitize-html configuration */
    private defaultHtmlSanitizeConfig;
    /**
     * Private constructor to enforce singleton pattern.
     */
    private constructor();
    /**
     * Get the singleton Sanitization instance.
     * @returns {Sanitization} The singleton instance.
     */
    static getInstance(): Sanitization;
    /**
     * Set sensitive fields for log sanitization. These fields will be redacted when
     * `sanitizeForLogging` is called.
     * @param {string[]} fields - Array of field names to consider sensitive.
     */
    setSensitiveFields(fields: string[]): void;
    /**
     * Get the current list of sensitive fields used for log sanitization.
     * @returns {string[]} Array of sensitive field names.
     */
    getSensitiveFields(): string[];
    /**
     * Sanitize HTML content using the `sanitize-html` library.
     * Removes potentially malicious tags and attributes.
     * @param {string} input - HTML string to sanitize.
     * @param {HtmlSanitizeConfig} [config] - Optional custom sanitization configuration.
     * @returns {string} Sanitized HTML string.
     */
    sanitizeHtml(input: string, config?: HtmlSanitizeConfig): string;
    /**
     * Sanitize string input based on context.
     *
     * **Important:** Using `context: 'javascript'` is explicitly disallowed and will throw an `McpError`.
     * This is a security measure to prevent accidental execution or ineffective sanitization of JavaScript code.
     *
     * @param {string} input - String to sanitize.
     * @param {SanitizeStringOptions} [options={}] - Sanitization options.
     * @returns {string} Sanitized string.
     * @throws {McpError} If `context: 'javascript'` is used.
     */
    sanitizeString(input: string, options?: SanitizeStringOptions): string;
    /**
     * Sanitize URL with robust validation.
     * Ensures the URL uses allowed protocols and is well-formed.
     * @param {string} input - URL to sanitize.
     * @param {string[]} [allowedProtocols=['http', 'https']] - Allowed URL protocols.
     * @returns {string} Sanitized URL.
     * @throws {McpError} If URL is invalid or uses a disallowed protocol.
     */
    sanitizeUrl(input: string, allowedProtocols?: string[]): string;
    /**
     * Sanitizes a file path to prevent path traversal and other common attacks.
     * Normalizes the path, optionally converts to POSIX style, and can restrict
     * the path to a root directory.
     *
     * @param {string} input - The file path to sanitize.
     * @param {PathSanitizeOptions} [options={}] - Options to control sanitization behavior.
     * @returns {SanitizedPathInfo} An object containing the sanitized path and metadata about the sanitization process.
     * @throws {McpError} If the path is invalid, unsafe (e.g., contains null bytes, attempts traversal).
     */
    sanitizePath(input: string, options?: PathSanitizeOptions): SanitizedPathInfo;
    /**
     * Sanitize a JSON string. Validates format and optionally checks size.
     * @template T - The expected type of the parsed JSON object.
     * @param {string} input - JSON string to sanitize.
     * @param {number} [maxSize] - Maximum allowed size in bytes.
     * @returns {T} Parsed and sanitized object.
     * @throws {McpError} If JSON is invalid, too large, or input is not a string.
     */
    sanitizeJson<T = unknown>(input: string, maxSize?: number): T;
    /**
     * Ensure input is a valid number and optionally within a numeric range.
     * Clamps the number to the range if min/max are provided and value is outside.
     * @param {number | string} input - Number or string to validate.
     * @param {number} [min] - Minimum allowed value (inclusive).
     * @param {number} [max] - Maximum allowed value (inclusive).
     * @returns {number} Sanitized number.
     * @throws {McpError} If input is not a valid number or parsable string.
     */
    sanitizeNumber(input: number | string, min?: number, max?: number): number;
    /**
     * Sanitize input for logging to protect sensitive information.
     * Deep clones the input and redacts fields matching `this.sensitiveFields`.
     * @param {unknown} input - Input to sanitize.
     * @returns {unknown} Sanitized input safe for logging.
     */
    sanitizeForLogging(input: unknown): unknown;
    /**
     * Private helper to convert attribute format for sanitize-html.
     */
    private convertAttributesFormat;
    /**
     * Recursively redact sensitive fields in an object or array.
     * Modifies the object in place.
     * @param {unknown} obj - The object or array to redact.
     */
    private redactSensitiveFields;
}
export declare const sanitization: Sanitization;
/**
 * Convenience function to sanitize input for logging.
 * @param {unknown} input - Input to sanitize.
 * @returns {unknown} Sanitized input safe for logging.
 */
export declare const sanitizeInputForLogging: (input: unknown) => unknown;
//# sourceMappingURL=sanitization.d.ts.map