/**
 * Filename and Display Name Sanitization Utilities
 * Prevents path traversal attacks and filesystem issues
 *
 * This module provides:
 * - Filename sanitization for safe filesystem storage
 * - Display name sanitization for user-facing content
 * - Path traversal prevention
 *
 * @see https://cheatsheetseries.owasp.org/cheatsheets/Input_Validation_Cheat_Sheet.html
 */
import type { SanitizeFileNameOptions, SanitizeDisplayNameOptions } from "../../types/index.js";
/**
 * Sanitize a filename for safe filesystem storage.
 * Removes characters that are invalid on various operating systems.
 *
 * @param filename - Raw filename to sanitize
 * @param options - Sanitization options
 * @returns Safe filename
 * @throws Error if filename is empty after sanitization
 *
 * @example
 * sanitizeFileName('my:file<name>.txt');
 * // Returns: 'my_file_name_.txt'
 *
 * @example
 * sanitizeFileName('../../../etc/passwd');
 * // Returns: '______etc_passwd'
 *
 * @example
 * sanitizeFileName('malware.exe', { blockDangerousExtensions: true });
 * // Throws: Error - dangerous extension
 */
export declare function sanitizeFileName(filename: string, options?: SanitizeFileNameOptions): string;
/**
 * Sanitize a display name for safe user-facing display.
 * Removes control characters and limits length.
 *
 * @param name - Raw display name to sanitize
 * @param options - Sanitization options
 * @returns Safe display name
 *
 * @example
 * sanitizeDisplayName('  John\x00Doe  ');
 * // Returns: 'John Doe'
 *
 * @example
 * sanitizeDisplayName('User<script>alert(1)</script>');
 * // Returns: 'User'
 */
export declare function sanitizeDisplayName(name: string, options?: SanitizeDisplayNameOptions): string;
/**
 * Validate a display name strictly.
 * Only allows alphanumeric, spaces, and basic punctuation.
 *
 * @param name - Display name to validate
 * @returns true if valid, false otherwise
 *
 * @example
 * isValidDisplayName('John Doe'); // true
 * isValidDisplayName('John<Doe'); // false
 */
export declare function isValidDisplayName(name: string): boolean;
/**
 * Validate a filename strictly.
 * Only allows alphanumeric, dash, underscore, and period.
 *
 * @param filename - Filename to validate
 * @returns true if valid, false otherwise
 *
 * @example
 * isValidFileName('my-file.txt'); // true
 * isValidFileName('../passwd'); // false
 */
export declare function isValidFileName(filename: string): boolean;
/**
 * Extract and sanitize the extension from a filename.
 *
 * @param filename - Filename to extract extension from
 * @returns Lowercase extension including the dot, or empty string
 *
 * @example
 * getFileExtension('document.PDF'); // '.pdf'
 * getFileExtension('noextension'); // ''
 */
export declare function getFileExtension(filename: string): string;
/**
 * Check if a file extension is considered dangerous.
 *
 * @param extension - File extension to check (with or without leading dot)
 * @returns true if extension is dangerous
 *
 * @example
 * isDangerousExtension('.exe'); // true
 * isDangerousExtension('pdf'); // false
 */
export declare function isDangerousExtension(extension: string): boolean;
/**
 * Generate a safe filename from arbitrary input.
 * Creates a valid filename even from completely invalid input.
 *
 * @param input - Any string input
 * @param defaultName - Default name if input sanitizes to empty (default: 'file')
 * @param extension - Optional extension to append
 * @returns Safe filename
 *
 * @example
 * generateSafeFileName('My Document!@#$'); // 'My_Document_'
 * generateSafeFileName('', 'untitled', '.txt'); // 'untitled.txt'
 */
export declare function generateSafeFileName(input: string, defaultName?: string, extension?: string): string;
/**
 * Get the list of dangerous file extensions.
 * Useful for validation UI or documentation.
 */
export declare function getDangerousExtensions(): string[];