content-security-toolkit 1.0.0

package/dist/strategies/AbstractStrategy.d.ts

@@ -0,0 +1,152 @@
+import type { ProtectionStrategy } from "../types";
+import type { MediatorAware, ProtectionMediator } from "../core/mediator/types";
+import { SimpleLoggingService } from "../utils/logging/simple/SimpleLoggingService";
+/**
+ * Error types for protection strategies
+ */
+export declare enum StrategyErrorType {
+    INITIALIZATION = "initialization",
+    APPLICATION = "application",
+    REMOVAL = "removal",
+    EVENT_HANDLING = "event_handling",
+    OPTION_UPDATE = "option_update",
+    UNKNOWN = "unknown"
+}
+/**
+ * Custom error class for protection strategies
+ */
+export declare class StrategyError extends Error {
+    readonly strategyName: string;
+    readonly errorType: StrategyErrorType;
+    readonly originalError?: (Error | unknown) | undefined;
+    /**
+     * Create a new StrategyError
+     * @param strategyName Name of the strategy where the error occurred
+     * @param errorType Type of error that occurred
+     * @param message Error message
+     * @param originalError Original error that was caught (if any)
+     */
+    constructor(strategyName: string, errorType: StrategyErrorType, message: string, originalError?: (Error | unknown) | undefined);
+}
+/**
+ * Abstract base class for protection strategies
+ * Implements common functionality to reduce duplication
+ */
+export declare abstract class AbstractStrategy implements ProtectionStrategy, MediatorAware {
+    readonly STRATEGY_NAME: string;
+    readonly COMPONENT_NAME: string;
+    protected debugMode: boolean;
+    protected mediator: ProtectionMediator | null;
+    protected isAppliedFlag: boolean;
+    protected logger: SimpleLoggingService;
+    protected eventIds: string[];
+    /**
+     * Create a new strategy
+     * @param strategyName Unique name for the strategy
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(strategyName: string, debugMode?: boolean);
+    /**
+     * Set the mediator
+     * to communicate with the other components
+     */
+    setMediator(mediator: ProtectionMediator): void;
+    /**
+     * Apply the protection strategy
+     * Must be implemented by subclasses
+     */
+    abstract apply(): void;
+    /**
+     * Remove the protection strategy
+     * Can be overridden by subclasses for custom cleanup
+     */
+    remove(): void;
+    /**
+     * Check if the strategy is currently applied
+     */
+    isApplied(): boolean;
+    /**
+     * Update strategy options
+     * Should be implemented by subclasses that support options
+     */
+    updateOptions(options: Record<string, unknown>): void;
+    /**
+     * Get the debug mode status
+     */
+    isDebugEnabled(): boolean;
+    /**
+     * Set debug mode
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Handle an error that occurred in the strategy
+     * @param errorType Type of error
+     * @param message Error message
+     * @param originalError Original error that was caught
+     */
+    protected handleError(errorType: StrategyErrorType, message: string, originalError?: unknown): void;
+    /**
+     * Log a debug message if debug mode is enabled
+     * @param message Message to log
+     * @param args Additional arguments to log
+     */
+    protected log(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message
+     * @param message Warning message
+     * @param args Additional arguments to log
+     */
+    protected warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message
+     * @param message Error message
+     * @param args Additional arguments to log
+     */
+    protected error(message: string, ...args: unknown[]): void;
+    /**
+     * Execute a function with error handling
+     * @param operation Name of the operation for error reporting
+     * @param errorType Type of error for categorization
+     * @param fn Function to execute
+     * @returns The result of the function or undefined if an error occurred
+     */
+    protected safeExecute<T>(operation: string, errorType: StrategyErrorType, fn: () => T): T | undefined;
+    /**
+     * Execute an async function with error handling
+     * @param operation Name of the operation for error reporting
+     * @param errorType Type of error for categorization
+     * @param fn Async function to execute
+     * @returns Promise resolving to the result of the function or undefined if an error occurred
+     */
+    protected safeExecuteAsync<T>(operation: string, errorType: StrategyErrorType, fn: () => Promise<T>): Promise<T | undefined>;
+    /**
+     * Register an event with the EventManager
+     * @param target The target element, document, or window
+     * @param eventType The type of event (e.g., "click", "keydown")
+     * @param handler The event handler function
+     * @param options Additional options for the event listener
+     * @returns The ID of the registered event
+     */
+    protected registerEvent(target: EventTarget | null, eventType: string, handler: EventListener, options?: AddEventListenerOptions & {
+        priority?: number;
+        id?: string;
+    }): string;
+    /**
+     * Remove all event listeners for this strategy
+     * @returns The number of events removed
+     */
+    protected removeEventsByOwner(): number;
+    /**
+     * Remove all event listeners for a specific target
+     * @param target The target to remove events from
+     * @returns The number of events removed
+     */
+    protected removeAllEventsForTarget(target: EventTarget | null): number;
+    /**
+     * Remove event listeners by CSS selector
+     * @param selector CSS selector to match elements
+     * @param eventType Type of event to remove
+     * @returns The number of events removed
+     */
+    protected removeEventsBySelector(selector: string, eventType: string): number;
+}

package/dist/strategies/AbstractStrategy.js

@@ -0,0 +1,296 @@
+import { eventManager } from "../utils/eventManager";
+import { isBrowser } from "../utils/environment";
+import { SimpleLoggingService } from "../utils/logging/simple/SimpleLoggingService";
+/**
+ * Error types for protection strategies
+ */
+export var StrategyErrorType;
+(function (StrategyErrorType) {
+    StrategyErrorType["INITIALIZATION"] = "initialization";
+    StrategyErrorType["APPLICATION"] = "application";
+    StrategyErrorType["REMOVAL"] = "removal";
+    StrategyErrorType["EVENT_HANDLING"] = "event_handling";
+    StrategyErrorType["OPTION_UPDATE"] = "option_update";
+    StrategyErrorType["UNKNOWN"] = "unknown";
+})(StrategyErrorType || (StrategyErrorType = {}));
+/**
+ * Custom error class for protection strategies
+ */
+export class StrategyError extends Error {
+    /**
+     * Create a new StrategyError
+     * @param strategyName Name of the strategy where the error occurred
+     * @param errorType Type of error that occurred
+     * @param message Error message
+     * @param originalError Original error that was caught (if any)
+     */
+    constructor(strategyName, errorType, message, originalError) {
+        super(`[${strategyName}] ${message}${originalError instanceof Error ? `: ${originalError.message}` : ""}`);
+        this.strategyName = strategyName;
+        this.errorType = errorType;
+        this.originalError = originalError;
+        this.name = "StrategyError";
+        // Maintain the stack trace
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, StrategyError);
+        }
+    }
+}
+/**
+ * Abstract base class for protection strategies
+ * Implements common functionality to reduce duplication
+ */
+export class AbstractStrategy {
+    /**
+     * Create a new strategy
+     * @param strategyName Unique name for the strategy
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(strategyName, debugMode = false) {
+        this.mediator = null;
+        this.isAppliedFlag = false;
+        this.eventIds = [];
+        this.STRATEGY_NAME = strategyName;
+        this.COMPONENT_NAME = strategyName;
+        this.debugMode = debugMode;
+        this.logger = new SimpleLoggingService(strategyName, debugMode);
+    }
+    /**
+     * Set the mediator
+     * to communicate with the other components
+     */
+    setMediator(mediator) {
+        this.mediator = mediator;
+        this.logger.log("Mediator set");
+    }
+    /**
+     * Remove the protection strategy
+     * Can be overridden by subclasses for custom cleanup
+     */
+    remove() {
+        try {
+            if (!this.isAppliedFlag) {
+                this.logger.log("Protection not applied");
+                return;
+            }
+            if (isBrowser()) {
+                // Remove all event listeners using EventManager
+                const removedCount = this.removeEventsByOwner();
+                // Clear the event IDs array
+                this.eventIds = [];
+                this.isAppliedFlag = false;
+                this.logger.log(`Protection removed (${removedCount} events)`);
+            }
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.REMOVAL, "Failed to remove protection", error);
+        }
+    }
+    /**
+     * Check if the strategy is currently applied
+     */
+    isApplied() {
+        return this.isAppliedFlag;
+    }
+    /**
+     * Update strategy options
+     * Should be implemented by subclasses that support options
+     */
+    updateOptions(options) {
+        try {
+            // Default implementation just logs that the method is not implemented
+            this.logger.log("Method updateOptions not implemented", options);
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.OPTION_UPDATE, "Failed to update options", error);
+        }
+    }
+    /**
+     * Get the debug mode status
+     */
+    isDebugEnabled() {
+        return this.debugMode;
+    }
+    /**
+     * Set debug mode
+     */
+    setDebugMode(enabled) {
+        this.debugMode = enabled;
+        this.logger.setDebugMode(enabled);
+        this.logger.log(`Debug mode ${enabled ? "enabled" : "disabled"}`);
+    }
+    /**
+     * Handle an error that occurred in the strategy
+     * @param errorType Type of error
+     * @param message Error message
+     * @param originalError Original error that was caught
+     */
+    handleError(errorType, message, originalError) {
+        const error = new StrategyError(this.STRATEGY_NAME, errorType, message, originalError);
+        if (this.debugMode) {
+            console.error(error);
+            if (error.originalError instanceof Error && error.originalError.stack) {
+                console.error("Original stack:", error.originalError.stack);
+            }
+        }
+        else {
+            console.error(error.message);
+        }
+    }
+    /**
+     * Log a debug message if debug mode is enabled
+     * @param message Message to log
+     * @param args Additional arguments to log
+     */
+    log(message, ...args) {
+        this.logger.log(message, ...args);
+    }
+    /**
+     * Log a warning message
+     * @param message Warning message
+     * @param args Additional arguments to log
+     */
+    warn(message, ...args) {
+        this.logger.warn(message, ...args);
+    }
+    /**
+     * Log an error message
+     * @param message Error message
+     * @param args Additional arguments to log
+     */
+    error(message, ...args) {
+        this.logger.error(message, ...args);
+    }
+    /**
+     * Execute a function with error handling
+     * @param operation Name of the operation for error reporting
+     * @param errorType Type of error for categorization
+     * @param fn Function to execute
+     * @returns The result of the function or undefined if an error occurred
+     */
+    safeExecute(operation, errorType, fn) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            this.handleError(errorType, `Error during ${operation}`, error);
+            return undefined;
+        }
+    }
+    /**
+     * Execute an async function with error handling
+     * @param operation Name of the operation for error reporting
+     * @param errorType Type of error for categorization
+     * @param fn Async function to execute
+     * @returns Promise resolving to the result of the function or undefined if an error occurred
+     */
+    async safeExecuteAsync(operation, errorType, fn) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            this.handleError(errorType, `Error during ${operation}`, error);
+            return undefined;
+        }
+    }
+    /**
+     * Register an event with the EventManager
+     * @param target The target element, document, or window
+     * @param eventType The type of event (e.g., "click", "keydown")
+     * @param handler The event handler function
+     * @param options Additional options for the event listener
+     * @returns The ID of the registered event
+     */
+    registerEvent(target, eventType, handler, options) {
+        if (!target || !isBrowser())
+            return "";
+        // Defensive check: ensure the provided target supports addEventListener
+        // This prevents runtime TypeError when non-DOM objects (Vue refs, selectors, etc.) are passed
+        // and provides a clearer StrategyError for easier debugging.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (typeof target.addEventListener !== "function") {
+            this.handleError(StrategyErrorType.EVENT_HANDLING, `Invalid event target for ${eventType} - target does not implement addEventListener`, new Error("target.addEventListener is not a function"));
+            return "";
+        }
+        try {
+            // Create a wrapped handler that includes error handling
+            const wrappedHandler = (event) => {
+                try {
+                    return handler(event);
+                }
+                catch (error) {
+                    this.handleError(StrategyErrorType.EVENT_HANDLING, `Error handling ${eventType} event`, error);
+                }
+            };
+            // Pass all options including priority to the eventManager
+            const eventId = eventManager.addEventListener(target, eventType, wrappedHandler, this.STRATEGY_NAME, options);
+            if (eventId) {
+                this.eventIds.push(eventId);
+                this.logger.log(`Registered ${eventType} event (ID: ${eventId})`);
+            }
+            return eventId;
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.EVENT_HANDLING, `Failed to register ${eventType} event`, error);
+            return "";
+        }
+    }
+    /**
+     * Remove all event listeners for this strategy
+     * @returns The number of events removed
+     */
+    removeEventsByOwner() {
+        try {
+            const removedCount = eventManager.removeEventsByOwner(this.STRATEGY_NAME);
+            if (removedCount > 0) {
+                this.logger.log(`Removed ${removedCount} events by owner ID`);
+            }
+            return removedCount;
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.REMOVAL, "Failed to remove events by owner", error);
+            return 0;
+        }
+    }
+    /**
+     * Remove all event listeners for a specific target
+     * @param target The target to remove events from
+     * @returns The number of events removed
+     */
+    removeAllEventsForTarget(target) {
+        if (!target || !isBrowser())
+            return 0;
+        try {
+            const removedCount = eventManager.removeAllEventsForTarget(target);
+            if (removedCount > 0) {
+                this.logger.log(`Removed ${removedCount} events from target`);
+            }
+            return removedCount;
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.REMOVAL, "Failed to remove events for target", error);
+            return 0;
+        }
+    }
+    /**
+     * Remove event listeners by CSS selector
+     * @param selector CSS selector to match elements
+     * @param eventType Type of event to remove
+     * @returns The number of events removed
+     */
+    removeEventsBySelector(selector, eventType) {
+        if (!isBrowser())
+            return 0;
+        try {
+            const removedCount = eventManager.removeEventsBySelector(selector, eventType, this.STRATEGY_NAME);
+            if (removedCount > 0) {
+                this.logger.log(`Removed ${removedCount} ${eventType} events via selector "${selector}"`);
+            }
+            return removedCount;
+        }
+        catch (error) {
+            this.handleError(StrategyErrorType.REMOVAL, `Failed to remove events by selector "${selector}"`, error);
+            return 0;
+        }
+    }
+}

package/dist/strategies/AbstractStrategy.mediator.d.ts

@@ -0,0 +1,162 @@
+import type { ProtectionStrategy } from "../types";
+import type { ProtectionMediator, ProtectionEventHandler, SubscriptionOptions } from "../core/mediator/types";
+import { ProtectionEventType } from "../core/mediator/protection-event";
+import type { EventDataMap } from "../core/mediator/eventDataTypes";
+/**
+ * Error types for protection strategies
+ */
+export declare enum StrategyErrorType {
+    INITIALIZATION = "initialization",
+    APPLICATION = "application",
+    REMOVAL = "removal",
+    EVENT_HANDLING = "event_handling",
+    OPTION_UPDATE = "option_update",
+    UNKNOWN = "unknown"
+}
+/**
+ * Custom error class for protection strategies
+ */
+export declare class StrategyError extends Error {
+    readonly strategyName: string;
+    readonly errorType: StrategyErrorType;
+    readonly originalError?: (Error | unknown) | undefined;
+    /**
+     * Create a new StrategyError
+     * @param strategyName Name of the strategy where the error occurred
+     * @param errorType Type of error that occurred
+     * @param message Error message
+     * @param originalError Original error that was caught (if any)
+     */
+    constructor(strategyName: string, errorType: StrategyErrorType, message: string, originalError?: (Error | unknown) | undefined);
+}
+/**
+ * Abstract base class for protection strategies
+ * Implements common functionality to reduce duplication
+ */
+export declare abstract class AbstractStrategy implements ProtectionStrategy {
+    protected mediator: ProtectionMediator | null;
+    protected subscriptionIds: string[];
+    readonly STRATEGY_NAME: string;
+    protected isAppliedFlag: boolean;
+    protected debugMode: boolean;
+    protected eventIds: string[];
+    /**
+     * Create a new strategy
+     * @param strategyName Unique name for the strategy
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(strategyName: string, debugMode?: boolean);
+    /**
+     * Apply the protection strategy
+     * Must be implemented by subclasses
+     */
+    abstract apply(): void;
+    /**
+     * Set the mediator for this strategy
+     * This connects the strategy to the event system
+     * @param mediator The protection mediator instance
+     */
+    setMediator(mediator: ProtectionMediator): void;
+    /**
+     * Helper method for subscribing to events
+     * Tracks subscription IDs for cleanup
+     */
+    protected subscribe(eventType: ProtectionEventType, handler: ProtectionEventHandler, options?: SubscriptionOptions): string;
+    /**
+     * Helper method for publishing events
+     */
+    protected publishEvent<T extends ProtectionEventType>(eventType: T, data?: EventDataMap[T]): void;
+    /**
+     * Remove the protection strategy
+     * Can be overridden by subclasses for custom cleanup
+     */
+    remove(): void;
+    /**
+     * Check if the strategy is currently applied
+     */
+    isApplied(): boolean;
+    /**
+     * Update strategy options
+     * Should be implemented by subclasses that support options
+     */
+    updateOptions(options: Record<string, unknown>): void;
+    /**
+     * Get the debug mode status
+     */
+    isDebugEnabled(): boolean;
+    /**
+     * Set debug mode
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Handle an error that occurred in the strategy
+     * @param errorType Type of error
+     * @param message Error message
+     * @param originalError Original error that was caught
+     */
+    protected handleError(errorType: StrategyErrorType, message: string, originalError?: unknown): void;
+    /**
+     * Log a debug message if debug mode is enabled
+     * @param message Message to log
+     * @param args Additional arguments to log
+     */
+    protected log(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message
+     * @param message Warning message
+     * @param args Additional arguments to log
+     */
+    protected warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message
+     * @param message Error message
+     * @param args Additional arguments to log
+     */
+    protected error(message: string, ...args: unknown[]): void;
+    /**
+     * Execute a function with error handling
+     * @param operation Name of the operation for error reporting
+     * @param errorType Type of error for categorization
+     * @param fn Function to execute
+     * @returns The result of the function or undefined if an error occurred
+     */
+    protected safeExecute<T>(operation: string, errorType: StrategyErrorType, fn: () => T): T | undefined;
+    /**
+     * Execute an async function with error handling
+     * @param operation Name of the operation for error reporting
+     * @param errorType Type of error for categorization
+     * @param fn Async function to execute
+     * @returns Promise resolving to the result of the function or undefined if an error occurred
+     */
+    protected safeExecuteAsync<T>(operation: string, errorType: StrategyErrorType, fn: () => Promise<T>): Promise<T | undefined>;
+    /**
+     * Register an event with the EventManager
+     * @param target The target element, document, or window
+     * @param eventType The type of event (e.g., "click", "keydown")
+     * @param handler The event handler function
+     * @param options Additional options for the event listener
+     * @returns The ID of the registered event
+     */
+    protected registerEvent(target: EventTarget | null, eventType: string, handler: EventListener, options?: AddEventListenerOptions & {
+        priority?: number;
+        id?: string;
+    }): string;
+    /**
+     * Remove all event listeners for this strategy
+     * @returns The number of events removed
+     */
+    protected removeEventsByOwner(): number;
+    /**
+     * Remove all event listeners for a specific target
+     * @param target The target to remove events from
+     * @returns The number of events removed
+     */
+    protected removeAllEventsForTarget(target: EventTarget | null): number;
+    /**
+     * Remove event listeners by CSS selector
+     * @param selector CSS selector to match elements
+     * @param eventType Type of event to remove
+     * @returns The number of events removed
+     */
+    protected removeEventsBySelector(selector: string, eventType: string): number;
+}