@designofadecade/server 4.0.0

package/dist/router/Routes.d.ts

@@ -0,0 +1,30 @@
+import type Router from './Router.js';
+import type { RouterRequest, RouterResponse, RouterMiddleware } from './Router.js';
+import type Context from '../context/Context.js';
+interface RouteRegistration {
+    path: string;
+    methods: string[];
+    pattern: URLPattern;
+    handler: (request: RouterRequest) => Promise<RouterResponse>;
+    middleware?: RouterMiddleware[];
+}
+export default class Routes {
+    #private;
+    /**
+     * Base path prefix for all routes in this class
+     * @type {string}
+     */
+    static basePath: string;
+    /**
+     * Array of nested route classes to register
+     * @type {Array}
+     */
+    static register: (new (router: Router, context?: Context) => Routes)[];
+    protected router: Router;
+    protected context?: Context;
+    constructor(router: Router, context?: Context);
+    get routerRoutes(): RouteRegistration[];
+    addRoute(path: string, methods: string | string[], handler: (request: RouterRequest) => Promise<RouterResponse>, middleware?: RouterMiddleware[]): void;
+}
+export {};
+//# sourceMappingURL=Routes.d.ts.map

package/dist/router/Routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Routes.d.ts","sourceRoot":"","sources":["../../src/router/Routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACnF,OAAO,KAAK,OAAO,MAAM,uBAAuB,CAAC;AAEjD,UAAU,iBAAiB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7D,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;CACjC;AAED,MAAM,CAAC,OAAO,OAAO,MAAM;;IACzB;;;OAGG;IACH,MAAM,CAAC,QAAQ,SAAM;IAErB;;;OAGG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,KAAK,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,MAAM,CAAC,EAAE,CAAM;IAG5E,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;gBAEhB,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;IAY7C,IAAI,YAAY,IAAI,iBAAiB,EAAE,CAEtC;IAED,QAAQ,CACN,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,EAC1B,OAAO,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,cAAc,CAAC,EAC5D,UAAU,CAAC,EAAE,gBAAgB,EAAE,GAC9B,IAAI;CAiCR"}

package/dist/router/Routes.js

@@ -0,0 +1,52 @@
+export default class Routes {
+    /**
+     * Base path prefix for all routes in this class
+     * @type {string}
+     */
+    static basePath = '';
+    /**
+     * Array of nested route classes to register
+     * @type {Array}
+     */
+    static register = [];
+    #routerRoutes = [];
+    router;
+    context;
+    constructor(router, context) {
+        this.router = router;
+        this.context = context;
+        this.constructor.register.forEach((RouteClass) => {
+            const route = new RouteClass(router, context);
+            this.#routerRoutes.push(...route.routerRoutes);
+        });
+    }
+    get routerRoutes() {
+        return this.#routerRoutes;
+    }
+    addRoute(path, methods, handler, middleware) {
+        // Validate inputs
+        if (typeof path !== 'string') {
+            throw new Error('Path must be a string');
+        }
+        if (typeof handler !== 'function') {
+            throw new Error('Handler must be a function');
+        }
+        const normalizedPath = `${this.constructor.basePath}${path}`.replace(/\/+/g, '/');
+        // Normalize methods to array
+        const methodsArray = Array.isArray(methods) ? methods : [methods];
+        // Validate HTTP methods
+        const validMethods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+        const invalidMethods = methodsArray.filter((m) => !validMethods.includes(m));
+        if (invalidMethods.length > 0) {
+            throw new Error(`Invalid HTTP methods: ${invalidMethods.join(', ')}`);
+        }
+        this.#routerRoutes.push({
+            path: normalizedPath,
+            methods: methodsArray,
+            pattern: new URLPattern({ pathname: normalizedPath }),
+            handler,
+            ...(middleware && { middleware }),
+        });
+    }
+}
+//# sourceMappingURL=Routes.js.map

package/dist/router/Routes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Routes.js","sourceRoot":"","sources":["../../src/router/Routes.ts"],"names":[],"mappings":"AAYA,MAAM,CAAC,OAAO,OAAO,MAAM;IACzB;;;OAGG;IACH,MAAM,CAAC,QAAQ,GAAG,EAAE,CAAC;IAErB;;;OAGG;IACH,MAAM,CAAC,QAAQ,GAA0D,EAAE,CAAC;IAE5E,aAAa,GAAwB,EAAE,CAAC;IAC9B,MAAM,CAAS;IACf,OAAO,CAAW;IAE5B,YAAY,MAAc,EAAE,OAAiB;QAC3C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAEtB,IAAI,CAAC,WAA6B,CAAC,QAAQ,CAAC,OAAO,CAClD,CAAC,UAA6D,EAAE,EAAE;YAChE,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC9C,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;QACjD,CAAC,CACF,CAAC;IACJ,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,aAAa,CAAC;IAC5B,CAAC;IAED,QAAQ,CACN,IAAY,EACZ,OAA0B,EAC1B,OAA4D,EAC5D,UAA+B;QAE/B,kBAAkB;QAClB,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QAC3C,CAAC;QAED,IAAI,OAAO,OAAO,KAAK,UAAU,EAAE,CAAC;YAClC,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;QAED,MAAM,cAAc,GAAG,GAAI,IAAI,CAAC,WAA6B,CAAC,QAAQ,GAAG,IAAI,EAAE,CAAC,OAAO,CACrF,MAAM,EACN,GAAG,CACJ,CAAC;QAEF,6BAA6B;QAC7B,MAAM,YAAY,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC;QAElE,wBAAwB;QACxB,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;QAClF,MAAM,cAAc,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7E,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,yBAAyB,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxE,CAAC;QAED,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;YACtB,IAAI,EAAE,cAAc;YACpB,OAAO,EAAE,YAAY;YACrB,OAAO,EAAE,IAAI,UAAU,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;YACrD,OAAO;YACP,GAAG,CAAC,UAAU,IAAI,EAAE,UAAU,EAAE,CAAC;SAClC,CAAC,CAAC;IACL,CAAC"}

package/dist/router/StaticFileHandler.d.ts

@@ -0,0 +1,44 @@
+interface ServeResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string | Buffer;
+}
+interface StaticFileHandlerOptions {
+    cacheControl?: string;
+}
+/**
+ * StaticFileHandler - Serves static files with security and proper MIME types
+ *
+ * Handles serving static files from a base directory with directory traversal
+ * protection, proper content types, and caching headers.
+ *
+ * @example
+ * const handler = new StaticFileHandler('./public');
+ * const response = await handler.serve('/assets/style.css');
+ */
+export default class StaticFileHandler {
+    #private;
+    static MIME_TYPES: Record<string, string>;
+    /**
+     * Create a new StaticFileHandler
+     *
+     * @param {string} baseDir - Base directory to serve files from (absolute path)
+     * @param {Object} options - Configuration options
+     * @param {string} [options.cacheControl='public, max-age=3600'] - Cache-Control header value
+     * @throws {Error} If baseDir is not a non-empty string
+     */
+    constructor(baseDir: string, options?: StaticFileHandlerOptions);
+    /**
+     * Serve a static file
+     *
+     * @param {string} requestPath - The requested file path
+     * @returns {Promise<Object>} Response object with status, headers, and body
+     *
+     * @example
+     * const response = await handler.serve('/assets/style.css');
+     * // Returns: { status: 200, headers: {...}, body: Buffer }
+     */
+    serve(requestPath: string): Promise<ServeResponse>;
+}
+export {};
+//# sourceMappingURL=StaticFileHandler.d.ts.map

package/dist/router/StaticFileHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StaticFileHandler.d.ts","sourceRoot":"","sources":["../../src/router/StaticFileHandler.ts"],"names":[],"mappings":"AAIA,UAAU,aAAa;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CACvB;AAED,UAAU,wBAAwB;IAChC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAiB;;IACpC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BvC;IAKF;;;;;;;OAOG;gBACS,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,wBAA6B;IAQnE;;;;;;;;;OASG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;CAsFzD"}

package/dist/router/StaticFileHandler.js

@@ -0,0 +1,148 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { logger } from '../logger/Logger.js';
+/**
+ * StaticFileHandler - Serves static files with security and proper MIME types
+ *
+ * Handles serving static files from a base directory with directory traversal
+ * protection, proper content types, and caching headers.
+ *
+ * @example
+ * const handler = new StaticFileHandler('./public');
+ * const response = await handler.serve('/assets/style.css');
+ */
+export default class StaticFileHandler {
+    static MIME_TYPES = {
+        '.html': 'text/html',
+        '.css': 'text/css',
+        '.js': 'text/javascript',
+        '.json': 'application/json',
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif',
+        '.svg': 'image/svg+xml',
+        '.ico': 'image/x-icon',
+        '.woff': 'font/woff',
+        '.woff2': 'font/woff2',
+        '.ttf': 'font/ttf',
+        '.otf': 'font/otf',
+        '.eot': 'application/vnd.ms-fontobject',
+        '.webp': 'image/webp',
+        '.pdf': 'application/pdf',
+        '.xml': 'application/xml',
+        '.txt': 'text/plain',
+        '.wasm': 'application/wasm',
+        '.mp4': 'video/mp4',
+        '.webm': 'video/webm',
+        '.mp3': 'audio/mpeg',
+        '.wav': 'audio/wav',
+        '.zip': 'application/zip',
+    };
+    #baseDir;
+    #cacheControl;
+    /**
+     * Create a new StaticFileHandler
+     *
+     * @param {string} baseDir - Base directory to serve files from (absolute path)
+     * @param {Object} options - Configuration options
+     * @param {string} [options.cacheControl='public, max-age=3600'] - Cache-Control header value
+     * @throws {Error} If baseDir is not a non-empty string
+     */
+    constructor(baseDir, options = {}) {
+        if (!baseDir || typeof baseDir !== 'string') {
+            throw new Error('baseDir must be a non-empty string');
+        }
+        this.#baseDir = path.resolve(baseDir);
+        this.#cacheControl = options.cacheControl || 'public, max-age=3600';
+    }
+    /**
+     * Serve a static file
+     *
+     * @param {string} requestPath - The requested file path
+     * @returns {Promise<Object>} Response object with status, headers, and body
+     *
+     * @example
+     * const response = await handler.serve('/assets/style.css');
+     * // Returns: { status: 200, headers: {...}, body: Buffer }
+     */
+    async serve(requestPath) {
+        try {
+            // Security: prevent directory traversal
+            // Resolve the full path and ensure it's within the base directory
+            const filePath = path.resolve(this.#baseDir, '.' + requestPath);
+            // Ensure file is within base directory (using resolve to handle .. properly)
+            const resolvedBase = path.resolve(this.#baseDir);
+            if (!filePath.startsWith(resolvedBase + path.sep) && filePath !== resolvedBase)
+                return {
+                    status: 403,
+                    headers: { 'Content-Type': 'text/plain' },
+                    body: 'Forbidden',
+                };
+            let stats = await fs.stat(filePath);
+            // Support index.html for directories
+            let finalPath = filePath;
+            if (stats.isDirectory()) {
+                finalPath = path.join(filePath, 'index.html');
+                try {
+                    stats = await fs.stat(finalPath);
+                }
+                catch {
+                    return {
+                        status: 404,
+                        headers: { 'Content-Type': 'text/plain' },
+                        body: 'Not Found',
+                    };
+                }
+            }
+            if (!stats.isFile())
+                return {
+                    status: 404,
+                    headers: { 'Content-Type': 'text/plain' },
+                    body: 'Not Found',
+                };
+            const content = await fs.readFile(finalPath);
+            const ext = path.extname(finalPath).toLowerCase();
+            const contentType = StaticFileHandler.MIME_TYPES[ext] || 'application/octet-stream';
+            // Add charset for text-based content
+            const fullContentType = contentType.startsWith('text/') ||
+                contentType.includes('javascript') ||
+                contentType.includes('json')
+                ? `${contentType}; charset=utf-8`
+                : contentType;
+            return {
+                status: 200,
+                headers: {
+                    'Content-Type': fullContentType,
+                    'Cache-Control': this.#cacheControl,
+                    'Content-Length': stats.size.toString(),
+                    'Last-Modified': stats.mtime.toUTCString(),
+                    'X-Content-Type-Options': 'nosniff',
+                },
+                body: content,
+            };
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return {
+                    status: 404,
+                    headers: { 'Content-Type': 'text/plain' },
+                    body: 'Not Found',
+                };
+            }
+            logger.error('Static file error', {
+                code: 'STATIC_FILE_ERROR',
+                source: 'StaticFileHandler.serve',
+                path: requestPath,
+                error,
+                errorCode: error.code,
+            });
+            return {
+                status: 500,
+                headers: { 'Content-Type': 'text/plain' },
+                body: 'Internal Server Error',
+            };
+        }
+    }
+}
+//# sourceMappingURL=StaticFileHandler.js.map

package/dist/router/StaticFileHandler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StaticFileHandler.js","sourceRoot":"","sources":["../../src/router/StaticFileHandler.ts"],"names":[],"mappings":"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"}

package/dist/sanitizer/HtmlSanitizer.d.ts

@@ -0,0 +1,306 @@
+/**
+ * HTML Sanitization Utility
+ *
+ * Production-grade HTML sanitization to prevent XSS attacks and ensure safe HTML rendering.
+ *
+ * Security Features:
+ * - XSS Prevention: Blocks dangerous protocols (javascript:, data:, vbscript:, etc.)
+ * - DoS Protection: Enforces maximum input size limits
+ * - Script/Style Removal: Completely removes script and style tags with content
+ * - HTML Comment Stripping: Removes comments that could hide malicious content
+ * - URL Validation: Validates and sanitizes URLs in anchor tags
+ * - Entity Decoding: Safely decodes HTML entities with range validation
+ * - Attribute Escaping: Prevents attribute injection attacks
+ *
+ * @module HtmlSanitizer
+ * @version 2.0.0
+ */
+/**
+ * Result type for sanitization methods
+ */
+export interface SanitizationResult {
+    readonly sanitized: string;
+    readonly warnings?: string[];
+}
+/**
+ * HTML Sanitization utility class with static methods for secure HTML processing
+ *
+ * @class HtmlSanitizer
+ */
+export default class HtmlSanitizer {
+    /**
+     * Cleans HTML by allowing only specified tags and removing all others.
+     *
+     * Features:
+     * - Strips disallowed tags while preserving text content
+     * - Validates and sanitizes URLs in anchor tags
+     * - Removes HTML comments, script, and style tags
+     * - Enforces DoS protection with size limits
+     * - Validates allowed tags is a valid array
+     *
+     * @param html - The HTML string to clean
+     * @param allowedTags - Array of allowed tag names (case-insensitive)
+     * @returns Sanitized HTML string with only allowed tags
+     *
+     * @example
+     * // Allow only paragraph and bold tags
+     * HtmlSanitizer.clean('<p>Hello <b>World</b></p><script>alert("xss")</script>', ['p', 'b']);
+     * // Returns: '<p>Hello <b>World</b></p>'
+     *
+     * @example
+     * // Sanitize anchor tags with URL validation
+     * HtmlSanitizer.clean('<a href="https://example.com">Safe</a><a href="javascript:alert(1)">Unsafe</a>', ['a']);
+     * // Returns: '<a href="https://example.com">Safe</a><a>Unsafe</a>'
+     *
+     * @example
+     * // Allow common formatting tags
+     * HtmlSanitizer.clean(userInput, ['p', 'br', 'strong', 'em', 'a', 'ul', 'ol', 'li']);
+     */
+    static clean(html: string, allowedTags: string[]): string;
+    /**
+     * Sanitizes basic HTML content by allowing only b, i, u, and a tags.
+     * Common use case for simple user-generated content.
+     *
+     * @param html - The HTML string to sanitize
+     * @returns Sanitized HTML string with basic formatting
+     *
+     * @example
+     * HtmlSanitizer.sanitizeBasicHtml('<b>Bold</b> and <i>italic</i> text');
+     * // Returns: '<b>Bold</b> and <i>italic</i> text'
+     */
+    static sanitizeBasicHtml(html: string): string;
+    /**
+     * Replaces or adds attributes to specific HTML tags.
+     * Useful for adding email-specific attributes like target="_blank" to links.
+     *
+     * @param html - The HTML string to process
+     * @param tagName - The tag name to target (e.g., 'a')
+     * @param attributes - Object with attribute key-value pairs to add/replace
+     * @returns HTML with updated tag attributes
+     *
+     * @example
+     * HtmlSanitizer.replaceTagAttributes('<a href="/link">Click</a>', 'a', {
+     *   target: '_blank',
+     *   style: 'color: blue;'
+     * });
+     * // Returns: '<a href="/link" target="_blank" style="color: blue;">Click</a>'
+     */
+    static replaceTagAttributes(html: string, tagName: string, attributes: Record<string, string>): string;
+    /**
+     * Strips all HTML tags from content, leaving only plain text.
+     * Removes comments, scripts, styles, and decodes HTML entities.
+     *
+     * @param html - The HTML string to strip
+     * @returns Plain text without any HTML tags
+     *
+     * @example
+     * HtmlSanitizer.stripAllTags('<p>Hello <b>World</b></p>');
+     * // Returns: 'Hello World'
+     *
+     * @example
+     * HtmlSanitizer.stripAllTags('<script>alert(1)</script>Safe text');
+     * // Returns: 'Safe text'
+     */
+    static stripAllTags(html: string): string;
+    /**
+     * Alias for stripAllTags() - strips all HTML tags from content.
+     * Provided for convenience and backwards compatibility.
+     *
+     * @param html - The HTML string to strip
+     * @returns Plain text without HTML tags
+     * @see stripAllTags
+     *
+     * @example
+     * HtmlSanitizer.stripAll('<div>Content</div>');
+     * // Returns: 'Content'
+     */
+    static stripAll(html: string): string;
+    /**
+     * Sanitizes text for safe use in HTML attributes.
+     * Escapes characters that could break out of attribute context or inject code.
+     *
+     * Escapes: &, ", ', <, >, newlines, carriage returns
+     *
+     * @param text - The text to sanitize
+     * @returns HTML-safe text for use in attributes
+     *
+     * @example
+     * HtmlSanitizer.sanitizeForAttribute('value with "quotes"');
+     * // Returns: 'value with &quot;quotes&quot;'
+     *
+     * @example
+     * const value = HtmlSanitizer.sanitizeForAttribute(userInput);
+     * // Safe in: <div data-value="${value}">...</div>
+     */
+    static sanitizeForAttribute(text: string): string;
+    /**
+     * Sanitizes text for safe display in HTML content.
+     * Escapes HTML special characters to prevent XSS attacks.
+     *
+     * Escapes: &, <, >, ", '
+     *
+     * @param text - The text to sanitize
+     * @returns HTML-safe text that can be inserted into HTML content
+     *
+     * @example
+     * HtmlSanitizer.sanitizeForHtml('<script>alert("xss")</script>');
+     * // Returns: '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'
+     *
+     * @example
+     * const safeText = HtmlSanitizer.sanitizeForHtml(userInput);
+     * // Safe in: <p>${safeText}</p>
+     */
+    static sanitizeForHtml(text: string): string;
+    /**
+     * Validates if a URL is safe for use in links.
+     * Blocks dangerous protocols and validates against common XSS vectors.
+     *
+     * Blocked protocols: javascript:, vbscript:, data:, file:, about:, blob:
+     * Allowed protocols: https://, http://, mailto:, tel:, sms:, relative paths
+     *
+     * @param url - The URL to validate
+     * @returns True if the URL is considered safe, false otherwise
+     *
+     * @example
+     * HtmlSanitizer.isValidUrl('https://example.com');
+     * // Returns: true
+     *
+     * @example
+     * HtmlSanitizer.isValidUrl('javascript:alert(1)');
+     * // Returns: false
+     *
+     * @example
+     * HtmlSanitizer.isValidUrl('/relative/path');
+     * // Returns: true
+     */
+    static isValidUrl(url: string): boolean;
+    /**
+     * Validates if an email address is properly formatted.
+     * Performs comprehensive email validation following RFC 5321/5322 standards.
+     *
+     * Validation Rules:
+     * - Maximum length: 254 characters (RFC 5321)
+     * - Local part (before @): 1-64 characters, allows a-z, 0-9, . _ + % -
+     * - Local part cannot start/end with dot or contain consecutive dots
+     * - Domain part (after @): 1-255 characters, requires valid TLD
+     * - Domain labels: 1-63 characters each, allows a-z, 0-9, hyphen (not at start/end)
+     * - Must contain exactly one @ symbol
+     * - Case-insensitive validation
+     *
+     * Security Features:
+     * - DoS protection with length limits
+     * - Rejects malformed patterns that could be used for injection
+     * - Validates against common email spoofing patterns
+     *
+     * Note: This performs format validation only. For production use, consider:
+     * - DNS MX record verification
+     * - Email verification (send confirmation email)
+     * - Third-party email validation services
+     * - Disposable email detection
+     *
+     * @param email - The email address to validate
+     * @returns True if email format is valid, false otherwise
+     *
+     * @example
+     * HtmlSanitizer.isValidEmail('user@example.com');
+     * // Returns: true
+     *
+     * @example
+     * HtmlSanitizer.isValidEmail('user+tag@subdomain.example.co.uk');
+     * // Returns: true
+     *
+     * @example
+     * HtmlSanitizer.isValidEmail('invalid.email');
+     * // Returns: false
+     *
+     * @example
+     * HtmlSanitizer.isValidEmail('user..name@example.com');
+     * // Returns: false (consecutive dots)
+     */
+    static isValidEmail(email: string): boolean;
+    /**
+     * Decodes common HTML entities to their character equivalents.
+     * Safely handles both named entities and numeric character references.
+     *
+     * Features:
+     * - Decodes common named entities (&amp;, &lt;, &nbsp;, etc.)
+     * - Decodes numeric entities (&#65; and &#x41; both -> 'A')
+     * - Validates character codes are in valid Unicode range
+     * - Excludes control characters (except tab, newline, CR)
+     *
+     * @param text - Text containing HTML entities
+     * @returns Text with entities decoded to characters
+     *
+     * @example
+     * HtmlSanitizer.decodeHtmlEntities('&lt;p&gt;Hello &amp; goodbye&lt;/p&gt;');
+     * // Returns: '<p>Hello & goodbye</p>'
+     *
+     * @example
+     * HtmlSanitizer.decodeHtmlEntities('&#65;&#66;&#67;'); // ABC
+     * HtmlSanitizer.decodeHtmlEntities('&#x41;&#x42;&#x43;'); // ABC
+     */
+    static decodeHtmlEntities(text: string): string;
+}
+/**
+ * USAGE GUIDELINES
+ *
+ * 1. USER-GENERATED CONTENT
+ *    Always sanitize user input before storing or displaying:
+ *    ```typescript
+ *    // For rich text with limited formatting
+ *    const sanitized = HtmlSanitizer.clean(userInput, ['p', 'br', 'strong', 'em', 'a']);
+ *
+ *    // For plain text display
+ *    const plainText = HtmlSanitizer.stripAll(userInput);
+ *    ```
+ *
+ * 2. ATTRIBUTE VALUES
+ *    Always escape text used in HTML attributes:
+ *    ```typescript
+ *    const safe = HtmlSanitizer.sanitizeForAttribute(userInput);
+ *    html = `<div data-value="${safe}">...</div>`;
+ *    ```
+ *
+ * 3. HTML CONTENT
+ *    Escape text to be displayed as-is in HTML:
+ *    ```typescript
+ *    const safe = HtmlSanitizer.sanitizeForHtml(userInput);
+ *    html = `<p>${safe}</p>`;
+ *    ```
+ *
+ * 4. ALLOWED TAGS
+ *    Choose the minimum set of tags needed:
+ *    - Basic formatting: ['b', 'i', 'u', 'br']
+ *    - Rich text: ['p', 'br', 'strong', 'em', 'a', 'ul', 'ol', 'li']
+ *    - Extended: ['p', 'br', 'strong', 'em', 'u', 'a', 'ul', 'ol', 'li', 'h1', 'h2', 'h3']
+ *
+ * 5. URL VALIDATION
+ *    URLs are automatically validated in anchor tags:
+ *    - Allowed: https://, http://, mailto:, tel:, sms:, relative paths
+ *    - Blocked: javascript:, data:, vbscript:, file:, blob:, about:
+ *
+ * 6. PERFORMANCE
+ *    - Input size limited to 1MB (DoS protection)
+ *    - Use stripAll() for better performance when HTML not needed
+ *    - Cache sanitized content when possible
+ *
+ * SECURITY NOTES
+ *
+ * - XSS Prevention: All dangerous protocols and scripts are blocked
+ * - DoS Protection: Input size limits prevent resource exhaustion
+ * - Context-Aware: Different methods for different contexts (attributes vs content)
+ * - Defense in Depth: Multiple layers of validation and sanitization
+ * - Logging: Security events are logged to console for monitoring
+ *
+ * LIMITATIONS
+ *
+ * - Does not validate HTML structure (unclosed tags, nesting rules)
+ * - Does not support CSS sanitization
+ * - Does not support SVG sanitization
+ * - Maximum input size: 1MB
+ * - Maximum URL length: 2048 characters
+ *
+ * @see https://owasp.org/www-community/attacks/xss/
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html
+ */
+//# sourceMappingURL=HtmlSanitizer.d.ts.map

package/dist/sanitizer/HtmlSanitizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HtmlSanitizer.d.ts","sourceRoot":"","sources":["../../src/sanitizer/HtmlSanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAeH;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CAC9B;AAmCD;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,aAAa;IAKhC;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM;IA2IzD;;;;;;;;;;OAUG;IACH,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAI9C;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,oBAAoB,CACzB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,MAAM;IA4CT;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAkCzC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAQrC;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IA2BjD;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IA6B5C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IA+EvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA0CG;IACH,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAuI3C;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAqFhD;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG"}