/**
 * HTML/XSS Sanitization Utilities
 * Context-aware output escaping following OWASP guidelines
 *
 * This module provides:
 * - HTML entity escaping for safe display
 * - JavaScript string escaping for embedding in scripts
 * - URL escaping for query parameters
 * - JSON string sanitization
 *
 * Pure TypeScript implementation with no external dependencies.
 *
 * @see https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html
 */
/**
 * Escape HTML special characters for safe insertion into HTML context.
 * Use this when you need to display user text as plain text (not HTML).
 *
 * OWASP Rule 1: HTML Encode Before Inserting Untrusted Data into HTML Element Content
 *
 * @param text - Raw text to escape
 * @returns HTML-escaped text safe for insertion into HTML
 *
 * @example
 * const userName = '<script>alert(1)</script>';
 * const safe = escapeHtml(userName);
 * // Returns: '&lt;script&gt;alert(1)&lt;/script&gt;'
 *
 * @example
 * // Safe to use in HTML
 * const html = `<div>${escapeHtml(userInput)}</div>`;
 */
export declare function escapeHtml(text: string): string;
/**
 * Unescape HTML entities back to their original characters.
 * Use with caution - only on trusted content.
 *
 * @param text - HTML-escaped text
 * @returns Unescaped text
 *
 * @example
 * const escaped = '&lt;div&gt;Hello&lt;/div&gt;';
 * const original = unescapeHtml(escaped);
 * // Returns: '<div>Hello</div>'
 */
export declare function unescapeHtml(text: string): string;
/**
 * Escape text for safe insertion into JavaScript string literals.
 * Use when embedding user data in inline JavaScript.
 *
 * OWASP Rule 3: JavaScript Encode Before Inserting Untrusted Data into JavaScript Data Values
 *
 * @param text - Raw text to escape
 * @returns JavaScript-escaped text safe for string literals
 *
 * @example
 * const userInput = "Hello\nWorld";
 * const safe = escapeJavaScript(userInput);
 * // Returns: 'Hello\\nWorld'
 *
 * @example
 * // Safe to use in inline script
 * const script = `const name = '${escapeJavaScript(userName)}';`;
 */
export declare function escapeJavaScript(text: string): string;
/**
 * Escape text for safe insertion into URLs.
 * Use for query parameter values.
 *
 * OWASP Rule 5: URL Encode Before Inserting Untrusted Data into URL Parameter Values
 *
 * @param text - Raw text to escape
 * @returns URL-encoded text safe for query parameters
 *
 * @example
 * const query = 'hello world&foo=bar';
 * const safe = escapeUrl(query);
 * // Returns: 'hello%20world%26foo%3Dbar'
 *
 * @example
 * // Safe to use in URL
 * const url = `https://example.com/search?q=${escapeUrl(userQuery)}`;
 */
export declare function escapeUrl(text: string): string;
/**
 * Decode URL-encoded text.
 *
 * @param text - URL-encoded text
 * @returns Decoded text
 *
 * @example
 * const encoded = 'hello%20world';
 * const decoded = decodeUrl(encoded);
 * // Returns: 'hello world'
 */
export declare function decodeUrl(text: string): string;
/**
 * Sanitize JSON string value to prevent injection attacks.
 * Ensures string can be safely used in JSON without breaking structure.
 *
 * @param value - Raw string value
 * @returns Escaped string safe for JSON values
 *
 * @example
 * const userInput = 'Hello\n"World"';
 * const safe = sanitizeJsonString(userInput);
 * // Returns: 'Hello\\n\\"World\\"'
 */
export declare function sanitizeJsonString(value: string): string;
/**
 * Escape text for safe insertion into CSS context.
 * Use when embedding user data in style attributes or stylesheets.
 *
 * OWASP Rule 4: CSS Encode And Strictly Validate Before Inserting Untrusted Data into HTML Style Property Values
 *
 * @param text - Raw text to escape
 * @returns CSS-escaped text
 *
 * @example
 * const userColor = 'red; background: url(evil.com)';
 * const safe = escapeCss(userColor);
 * // Escapes dangerous characters
 */
export declare function escapeCss(text: string): string;
/**
 * Strip all HTML tags from content, leaving only text.
 * Useful for extracting plain text from HTML.
 *
 * @param html - HTML content
 * @returns Plain text with all tags removed
 *
 * @example
 * const html = '<p>Hello <b>World</b></p>';
 * const text = stripHtmlTags(html);
 * // Returns: 'Hello World'
 */
export declare function stripHtmlTags(html: string): string;
/**
 * Escape text for safe use in XML/XHTML context.
 * Similar to HTML escaping but uses XML numeric entities.
 *
 * @param text - Raw text to escape
 * @returns XML-escaped text
 */
export declare function escapeXml(text: string): string;
/**
 * Sanitize content for safe inclusion in HTML attributes.
 * More aggressive than escapeHtml - also handles newlines and tabs.
 *
 * @param value - Attribute value to sanitize
 * @returns Sanitized attribute value
 *
 * @example
 * const attr = 'value" onclick="alert(1)';
 * const safe = sanitizeHtmlAttribute(attr);
 * // Returns: 'value&quot; onclick=&quot;alert(1)'
 */
export declare function sanitizeHtmlAttribute(value: string): string;
/**
 * Check if a string contains potentially dangerous HTML content.
 * Does NOT sanitize - use other functions for that.
 *
 * @param text - Text to check
 * @returns true if text contains dangerous patterns
 *
 * @example
 * containsDangerousHtml('<script>alert(1)</script>'); // true
 * containsDangerousHtml('Hello World'); // false
 */
export declare function containsDangerousHtml(text: string): boolean;