content-security-toolkit 1.0.0

package/dist/strategies/AbstractStrategy.mediator.js

@@ -0,0 +1,349 @@
+import { eventManager } from "../utils/eventManager";
+import { isBrowser } from "../utils/detection";
+import { ProtectionEventType } from "../core/mediator/protection-event";
+/**
+ * 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.subscriptionIds = []; // For tracking event subscriptions
+        this.isAppliedFlag = false;
+        this.debugMode = false;
+        this.eventIds = [];
+        this.STRATEGY_NAME = strategyName;
+        this.debugMode = debugMode;
+    }
+    /**
+     * Set the mediator for this strategy
+     * This connects the strategy to the event system
+     * @param mediator The protection mediator instance
+     */
+    setMediator(mediator) {
+        if (this.mediator === mediator)
+            return; // Avoid redundant setup
+        // Clean up any existing subscriptions if we're changing mediators
+        if (this.mediator && this.subscriptionIds.length > 0) {
+            this.subscriptionIds.forEach((id) => this.mediator?.unsubscribe(id));
+            this.subscriptionIds = [];
+        }
+        this.mediator = mediator;
+        this.log(`Connected to mediator`);
+        // Base class doesn't subscribe to any events by default
+        // Specific strategies will override this method to add their subscriptions
+    }
+    /**
+     * Helper method for subscribing to events
+     * Tracks subscription IDs for cleanup
+     */
+    subscribe(eventType, handler, options) {
+        if (!this.mediator) {
+            this.warn(`Cannot subscribe to ${eventType} - no mediator set`);
+            return "";
+        }
+        const id = this.mediator.subscribe(eventType, handler, {
+            ...options,
+            context: this.STRATEGY_NAME, // Always include strategy name as context
+        });
+        if (id) {
+            this.subscriptionIds.push(id);
+        }
+        return id;
+    }
+    /**
+     * Helper method for publishing events
+     */
+    publishEvent(eventType, data) {
+        if (!this.mediator) {
+            this.warn(`Cannot publish ${eventType} - no mediator set`);
+            return;
+        }
+        this.mediator.publish({
+            type: eventType,
+            source: this.STRATEGY_NAME,
+            timestamp: Date.now(),
+            data: data, // Explicit type assertion
+        });
+    }
+    /**
+     * Remove the protection strategy
+     * Can be overridden by subclasses for custom cleanup
+     */
+    remove() {
+        try {
+            if (!this.isAppliedFlag) {
+                this.log("Protection not applied");
+                return;
+            }
+            // Unsubscribe from all events
+            if (this.mediator && this.subscriptionIds.length > 0) {
+                this.subscriptionIds.forEach((id) => {
+                    this.mediator?.unsubscribe(id);
+                });
+                this.subscriptionIds = [];
+                this.log("Unsubscribed from all events");
+            }
+            if (isBrowser()) {
+                // Remove all event listeners using EventManager
+                const removedCount = this.removeEventsByOwner();
+                // Clear the event IDs array
+                this.eventIds = [];
+                this.isAppliedFlag = false;
+                this.log(`Protection removed (${removedCount} events)`);
+                // Publish event that strategy was removed
+                this.publishEvent(ProtectionEventType.STRATEGY_REMOVED);
+            }
+        }
+        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
+     */
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    updateOptions(options) {
+        try {
+            // Default implementation just logs that the method is not implemented
+            this.log("Method updateOptions not implemented");
+        }
+        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.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) {
+        if (this.debugMode) {
+            console.log(`${this.STRATEGY_NAME}: ${message}`, ...args);
+        }
+    }
+    /**
+     * Log a warning message
+     * @param message Warning message
+     * @param args Additional arguments to log
+     */
+    warn(message, ...args) {
+        if (this.debugMode) {
+            console.warn(`${this.STRATEGY_NAME}: ${message}`, ...args);
+        }
+        else {
+            // In non-debug mode, only log the message without args for brevity
+            console.warn(`${this.STRATEGY_NAME}: ${message}`);
+        }
+    }
+    /**
+     * Log an error message
+     * @param message Error message
+     * @param args Additional arguments to log
+     */
+    error(message, ...args) {
+        console.error(`${this.STRATEGY_NAME}: ${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 "";
+        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.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.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.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.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/ClipboardStrategy.d.ts

@@ -0,0 +1,67 @@
+import { AbstractStrategy } from "./AbstractStrategy";
+import type { ClipboardOptions } from "../types";
+import type { CustomEventHandlers } from "../types";
+/**
+ * Strategy to prevent copying content via clipboard operations
+ * Blocks copy, cut, and optionally paste operations
+ */
+export declare class ClipboardStrategy extends AbstractStrategy {
+    private options;
+    private targetElement;
+    private customHandler?;
+    private originalClipboardWriteText;
+    private originalClipboardReadText;
+    private originalExecCommand;
+    /**
+     * Create a new ClipboardStrategy
+     * @param options Configuration options
+     * @param targetElement Target element to protect (defaults to document.body)
+     * @param customHandler Custom handler for clipboard events
+     * @param debugMode Enable debug mode for troubleshooting
+     */
+    constructor(options?: ClipboardOptions, targetElement?: HTMLElement | null, customHandler?: CustomEventHandlers["onClipboardAttempt"], debugMode?: boolean);
+    /**
+     * Apply clipboard protection
+     */
+    apply(): void;
+    /**
+     * Remove clipboard protection
+     */
+    remove(): void;
+    /**
+     * Update clipboard protection options
+     * @param options New options to apply
+     */
+    updateOptions(options: Partial<ClipboardOptions>): void;
+    /**
+     * Handle copy event
+     * @param event Copy event
+     */
+    private handleCopy;
+    /**
+     * Handle cut event
+     * @param event Cut event
+     */
+    private handleCut;
+    /**
+     * Handle paste event
+     * @param event Paste event
+     */
+    private handlePaste;
+    /**
+     * Intercept the Clipboard API to prevent programmatic access
+     */
+    private interceptClipboardAPI;
+    /**
+     * Restore original Clipboard API methods
+     */
+    private restoreClipboardAPI;
+    /**
+     * Intercept document.execCommand to prevent clipboard operations
+     */
+    private interceptExecCommand;
+    /**
+     * Restore original document.execCommand
+     */
+    private restoreExecCommand;
+}